The GitHub integration connects GitHub accounts to your Probara organization through the Probara GitHub App. Once it is installed, your team can:
- link GitHub issues to test cases, test runs and defects;
- create a GitHub issue from a defect or a failed result, prefilled with the test case;
- keep a defect and its issues in sync: resolving the defect closes the issue, closing the issue resolves the defect;
- build traceability reports from GitHub issues;
- launch automated runs in GitHub Actions and get a results comment on each pull request. That part has its own guide: Running tests with GitHub Actions.
Before you start
| You need | Why |
|---|---|
| A paid plan (Pro or Enterprise, or any trial) | Integrations are not part of the Free plan. On Free, the GitHub dialog shows See plans instead of Install on GitHub. |
| A Probara owner or admin | Only owners and admins can install the app, disconnect an account and choose a project’s repositories. |
| An owner of the GitHub organization, or the owner of a personal account | GitHub only lets them install apps on the account. |
| A repository on github.com | GitHub Enterprise Server is not supported. |
Install the GitHub App
- In Workspace › Integrations, select the GitHub card.
- Select Install on GitHub. GitHub opens in the same tab.
- Choose the GitHub account or organization to install the app on.
- Choose All repositories, or Only select repositories and pick them. You can change this later in GitHub without coming back to Probara.
- Approve the install. GitHub then asks you to authorize Probara: this lets Probara check that your GitHub account can see the installation before it attaches it to your organization.
- GitHub sends you back to Probara, which shows GitHub is connected. Select Go to Integrations.
The account now appears under Connected accounts in the GitHub dialog, with its repository access (All repositories or Selected repositories) and status Active. Select Show repositories to see what the app can reach.
The connection belongs to your Probara organization. Nobody in another organization can see its repositories, and one installation can be connected to only one Probara organization at a time. To work with several GitHub accounts or organizations, install the app on each of them.
The install link is valid for 10 minutes and works once. If it expired, start again from Install on GitHub.
What the app may do in GitHub
GitHub shows these permissions when you install the app:
| Permission | Access | Used for |
|---|---|---|
| Metadata | Read | Listing the repositories you granted |
| Contents | Read | Listing branches when you launch a workflow |
| Issues | Write | Searching, creating, closing and reopening issues |
| Actions | Write | Listing workflows and starting them |
| Pull requests | Write | Posting the run summary comment on a pull request |
The app also receives GitHub’s issue and workflow run events, which is how status changes and build updates reach Probara.
Choose a project’s repositories
By default, a project offers every repository the GitHub app can see when someone links an issue, creates one or launches a workflow. To narrow that down:
- Open the project’s Settings › GitHub.
- Under GitHub repositories, select the repositories this project works with.
- Optionally, mark one as Default. It is preselected when someone creates an issue.
- Select Save repositories.
Once at least one repository is selected, the project uses only those repositories: links, searches, new issues, traceability reports, workflow launches and pull request comments are all limited to them. Clear every repository to go back to offering all of them.
Link GitHub issues
You can link issues on three places:
| Where | Section | Default kind |
|---|---|---|
| Test case | Properties tab or the full editor, GitHub issues | Requirement |
| Test run | Defects tab, GitHub issues | Defect |
| Defect | Defect page, GitHub issues | Defect |
- Select Link GitHub issue.
- Choose a Repository.
- Under Issue, type words from the title, or
#123for an issue number. - Under Link as, keep the default kind or change it.
- Select the issue in the list, then click Link issue.
The kind decides what the link is for:
- Requirement: the issue describes what the case verifies. Requirement links on test cases are what traceability reports count as coverage.
- Defect: the issue tracks a bug. Defect links on a defect keep the defect’s status in sync with the issue (see below).
Linking an existing issue writes nothing to GitHub. To remove a link, select the × next to it and confirm: the issue stays in GitHub.
Issue details and preview
Each link shows the issue as owner/repository#number, its title, its kind and its state (Open
or Closed). Hover over the reference to preview its labels, who opened it and when Probara last
read it from GitHub, with Open on GitHub.
Probara keeps a copy of these details, updated every time GitHub reports a change to the issue. When GitHub is unreachable, links still show the last details read. Select Refresh from GitHub on a link to read it again right away.
Create an issue from a defect or a failed result
- From a defect: on the defect page, under GitHub issues, select Create GitHub issue.
- From a failed result: when you report a defect from a failed or blocked result, select Also create a GitHub issue in the Report defect dialog. Once the defect is saved, the create dialog opens.
In Create a GitHub issue, choose the Repository, review the Title and Description, optionally pick Labels from that repository, and select Create issue. The issue is linked to the defect as a Defect link.
The text is prefilled and you can edit all of it:
| Prefilled from | Title | Description |
|---|---|---|
| A defect | The defect’s title | The defect’s description and links to its attachments |
| A failed result | The test case’s title | Also the test case, its preconditions, its steps with expected and actual results, the failure comment, and the run, environment and configuration |
The description ends with links back to the defect, the test case and the run in Probara, and the name of the person who filed it. In GitHub, the Probara app shows as the issue’s author.
Attachments stay in Probara. The description links to each file; opening one requires access to the project in Probara.
Retrying is safe. If GitHub does not confirm the new issue, Probara says so. Try again in a moment: Probara first looks for the issue it already opened, and only creates one if it finds none.
Status sync
A defect and the GitHub issues linked to it as Defect keep their status in sync in both directions. Links of kind Requirement, and links on test cases and runs, never change a status.
| When this happens | The other side |
|---|---|
| The defect becomes Resolved or Closed with resolution Fixed, or none | The issue is closed as completed |
| The defect becomes Resolved or Closed with another resolution | The issue is closed as not planned |
| The defect is reopened from Resolved or Closed | The issue is reopened |
| The issue is closed as completed (or as a duplicate) | The defect becomes Resolved, resolution Fixed |
| The issue is closed as not planned | The defect becomes Resolved, resolution Won’t fix |
| The issue is reopened | A Resolved or Closed defect goes back to Open |
In progress is not synced: moving a defect between Open and In progress changes nothing in GitHub. A defect with several linked issues follows each of them, and its change goes to all its other issues. Changes made from GitHub appear in the defect’s activity as made by the system.
If GitHub is unavailable when a defect changes, Probara keeps retrying for up to 7 days.
Pull request comments
When a run reported from GitHub Actions for a pull request is closed or aborted, Probara can post its results on that pull request: the outcome, a table of counts, pass rate, duration and commit, up to 10 failed or blocked cases each with a View result link to that case in the run, and the earlier runs of the pull request. Every comment is a new one, so the pull request notifies its participants, and Probara hides its previous comment as outdated. A hidden comment stays on the pull request: select Show comment to read it.
Choose when a project comments in its Settings › GitHub, under Pull request comments (owners and admins):
| Option | Comments |
|---|---|
| After every run | Every closed or aborted run. |
| Only when tests fail | A run with failed or blocked cases, or an aborted run. When a later run passes, one more comment says it passes. |
| Never | Nothing. |
Only when tests fail is the default.
A run gets a comment only when it records the GitHub Actions pull request it ran for. See Running tests with GitHub Actions.
Traceability with GitHub
GitHub issues can be the requirements of a traceability report. Reports, versions, filters and the CSV export work as they do with Jira; only the choice of requirements differs.
- Link the issues as Requirement on the test cases that verify them.
- In the project’s Traceability, select Create report. When Jira is connected too, choose GitHub as Tracker.
- Choose one or more Repository (up to 20). The list follows the project’s repositories.
- Optionally narrow the issues:
- Labels: issues must carry every selected label. Leave it empty for any label.
- Milestone: a milestone title. A repository without that milestone adds no issues.
- Issue state: Open and closed (default), Open or Closed.
- Select Create report.
Pull requests are never requirements. In a version, each requirement shows as
owner/repository#number with the status Open, Closed or Closed as not planned; the
Requirement status filter counts open issues as To do and closed ones as Done. A test case covers
an issue when it links it as Requirement.
Disconnect or uninstall
| Goal | Where | What happens |
|---|---|---|
| Stop using an account | Workspace › Integrations › GitHub, select Disconnect on the account and confirm. | Probara stops working with its repositories. The app stays installed on GitHub until you uninstall it there. |
| Remove the app from GitHub | In GitHub, uninstall the Probara app from the account’s installed GitHub Apps. | The account shows Needs attention in Probara. Disconnect it there. |
A suspended installation also shows Needs attention until you unsuspend it in GitHub. Links already made stay visible with the details Probara last read.
Troubleshooting
| Message | What to do |
|---|---|
| ”The GitHub app is not available in this environment yet.” | The app is not set up for your environment. Contact Probara support. |
| ”Your GitHub account cannot see this installation. Install the app with a GitHub account that administers it.” | Install again from Probara with a GitHub account that owns or administers the GitHub account or organization. |
| ”This GitHub installation is already connected to a workspace.” | The installation belongs to another Probara organization. Disconnect it there first. |
| ”This install link is invalid or has expired. Start again from Integrations.” | Select Install on GitHub again. |
| ”GitHub no longer lets Probara use this installation. Check the account in Integrations.” | The app was uninstalled or suspended in GitHub. Unsuspend it, or disconnect the account and install the app again. |
| ”This project does not link issues from that repository.” | The project’s Settings › GitHub leaves that repository out. An owner or admin adds it. |
| ”The GitHub installation cannot see this repository.” | In GitHub, give the app access to the repository (the installation’s Repository access setting). |
| ”That number is a pull request. Only issues can be linked.” | Pull requests cannot be linked. Pick an issue. |
| ”Issues are turned off in this GitHub repository.” | Turn on Issues in the repository’s settings in GitHub, or choose another repository. |
| ”GitHub refused the issue. Check the labels and try again.” | Remove the labels that no longer exist in the repository. |
| No Link GitHub issue button | No GitHub account is connected, your plan does not include integrations, or your role cannot edit that test case, run or defect. |
Launch errors, such as a workflow that cannot be started, are in Running tests with GitHub Actions.
Security and data
- Credentials. Probara holds no GitHub password or personal token. It acts as the app, with short-lived tokens limited to the repositories you granted, and only from Probara’s servers.
- What Probara stores: the connected account’s name, and for each link the repository, issue number, title, state, labels, author and URL.
- What Probara writes to GitHub: the issues you create, the closing and reopening of issues linked to defects as Defect, and the summary comment on pull requests.
- Audit. Connecting and disconnecting accounts, changing a project’s repositories or its pull request comments setting, linking, unlinking and creating issues, and launching workflows are recorded in Workspace activity.
Automate with the API and MCP
Scripts and AI assistants can do the day-to-day GitHub work with an API token or through Probara MCP: list, link, refresh and unlink issues on test cases, runs and defects; search a repository’s issues; create an issue from a defect; read a project’s repositories; and launch workflows. Installing the app, disconnecting an account, choosing a project’s repositories and turning pull request comments on or off stay in the web app.
The endpoints are in the GitHub API page, and every MCP tool in the MCP tool reference.