# GitHub

> Install the GitHub app of Troopy, choose the repos, and set the commands that the Engineer runs.

Connect GitHub so that the Engineer builds and fixes things in your repos. Each task gets its own branch, and your tests
run on the computer of your troop. Only a change that passes them becomes a pull request for you to review. Troopy
merges only when a person releases a ticket, and only pushes branches named `troopy/…`.

## Before you begin

- Only owners and admins connect GitHub.
- GitHub connects with the GitHub App of Troopy, and not with a key.
- You must be the owner of the account, or an admin of the repos of the organization that the app reaches.

## Connect GitHub

1. Open **Settings** > **Apps**, select the tile of GitHub, and select **Connect GitHub** on its card.
2. On GitHub, pick the account or the organization, and the repos that Troopy may reach.
3. Install the app. GitHub sends you back to Troopy.
4. The card shows "GitHub is connected", and lists each repo.

To add or remove repos later, select **Choose repos on GitHub**.

## Set the commands of each repo

The Engineer runs the commands of each repo on the computer of your troop. Check them on the card:

| Command                                | What it does                              | Example    |
| -------------------------------------- | ----------------------------------------- | ---------- |
| **Setup (installs, with network)**     | Installs what the repo needs.             | `npm ci`   |
| **Test (checks a change, no network)** | Checks a change. It runs with no network. | `npm test` |

Select **Save**. A repo with no test command shows "No test command: changes here can't be checked".

## What Troopy does in GitHub

| Action                                 | When                                                                                    |
| -------------------------------------- | --------------------------------------------------------------------------------------- |
| Reads the code at one commit           | When the Engineer studies a ticket, with read-only access.                              |
| Pushes a branch `troopy/<key>-<title>` | When the Engineer builds a ticket, after the tests of the repo passed.                  |
| Opens a pull request as a draft        | After the push. It becomes ready for review when every gate passed.                     |
| Comments on the pull request           | When the QA tester tests a ticket, in a private repo only, if Settings > Tests lets it. |
| Merges the tested commit               | Only when a person presses **Release**, or under an auto-release grant.                 |

Troopy never pushes other branches, and its app has no permission on workflows. Troopy mints a token for each call, for
one repo with the least access, and revokes it after the call.

## Disconnect GitHub

Select **Disconnect** on the card. To remove the app from the repos too, uninstall it on GitHub.

## Problems

| Message                                                                                            | What to do                                                                                 |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| "Your GitHub organization's admin has to approve Troopy's app first."                              | Ask the admin of the organization to approve it, then connect again.                       |
| "That installation isn't on your GitHub account, or you aren't an admin of every repo it reaches." | Install it on your own account, or ask an admin of the repos.                              |
| "That GitHub account is connected to another Troopy organization."                                 | One installation belongs to one organization. Use another account, or disconnect it there. |
| "The app doesn't reach any repos yet."                                                             | Select **Choose repos on GitHub**, and add repos.                                          |
| "GitHub didn't answer as expected. Try again in a minute."                                         | Wait a minute, and connect again.                                                          |

## Related

- [Ship code with engineering tickets](/docs/engineering)
- [Test your product with the QA tester](/docs/tests)
- [Catch the errors of your apps](/docs/incidents)
- [Stay in control of your troop](/docs/control)