# GitHub integration > Install the Probara GitHub App, link issues to test cases, runs and defects, create issues from failures, and keep defect status in sync. 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](https://docs.probara.net/en/guides/integrations/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 1. In **Workspace › Integrations**, select the **GitHub** card. 2. Select **Install on GitHub**. GitHub opens in the same tab. 3. Choose the GitHub account or organization to install the app on. 4. Choose **All repositories**, or **Only select repositories** and pick them. You can change this later in GitHub without coming back to Probara. 5. 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. 6. 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: 1. Open the project's **Settings › GitHub**. 2. Under **GitHub repositories**, select the repositories this project works with. 3. Optionally, mark one as **Default**. It is preselected when someone creates an issue. 4. 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** | 1. Select **Link GitHub issue**. 2. Choose a **Repository**. 3. Under **Issue**, type words from the title, or `#123` for an issue number. 4. Under **Link as**, keep the default kind or change it. 5. 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](https://docs.probara.net/en/guides/integrations/github-actions/#pull-request-comments). ## Traceability with GitHub GitHub issues can be the requirements of a [traceability report](https://docs.probara.net/en/guides/integrations/jira-traceability/). Reports, versions, filters and the CSV export work as they do with Jira; only the choice of requirements differs. 1. Link the issues as **Requirement** on the test cases that verify them. 2. In the project's **Traceability**, select **Create report**. When Jira is connected too, choose **GitHub** as **Tracker**. 3. Choose one or more **Repository** (up to 20). The list follows the project's repositories. 4. 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**. 5. 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](https://docs.probara.net/en/guides/integrations/github-actions/#troubleshooting). ## 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](https://docs.probara.net/en/guides/workspace/activity/). ## Automate with the API and MCP Scripts and AI assistants can do the day-to-day GitHub work with an [API token](https://docs.probara.net/en/developers/authentication/) or through [Probara MCP](https://docs.probara.net/en/developers/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](https://docs.probara.net/en/developers/api/github/) page, and every MCP tool in the [MCP tool reference](https://docs.probara.net/en/developers/mcp-tools/).