Connect GitHub repositories

You connect GitHub by installing the Tracewell app on your GitHub organization. Tracewell can then read the repositories you select, and nothing else: it can’t push, open pull requests or change settings.

Before you start

• You’re an admin of your Tracewell workspace.
• You need to be an owner of the GitHub organization. A member who isn’t an owner can only request the app, and an owner then has to connect it.

Connect your repositories

1. In Tracewell, open Settings → Connections and select the GitHub card, then Continue to GitHub.
2. GitHub asks you to authorize Tracewell. Select Authorize. Tracewell only uses this to see which organizations have its app installed that you can access; it never acts as you. If you authorized it before, GitHub sends you straight back.
3. Tracewell lists those organizations with the repositories the app reads in each. Select Connect next to the organization.

If the app isn’t installed on your organization yet:

1. Select Install on another organization. GitHub shows the installation page of the Tracewell app.
2. Choose the organization.
3. Under Repository access, select Only select repositories and pick the repositories Tracewell should read. All repositories works too, and includes the repositories you create later.
4. Check the permissions GitHub lists: read access to code and metadata. Tracewell asks for nothing else.
5. Select Install. GitHub sends you back to Tracewell, which connects the repositories you picked.

Tracewell then shows the GitHub page with the repositories it connected.

Add or remove repositories

Open the GitHub card in Settings and select Add repositories. Next to the organization, select Change repositories on GitHub, change the selection and select Save. GitHub sends you back, and Tracewell connects the repositories you added and disconnects the ones you removed.

To connect a disconnected repository again, select Connect again next to it. Tracewell connects that repository only. If the app no longer reads it at GitHub, Tracewell says so: select Select it on GitHub, select the repository and Save, and GitHub sends you back with the repository connected.

If you change the selection in your organization’s settings instead, Tracewell stops reading a removed repository right away, and its card shows an error. It only sees an added repository after you connect GitHub again from Settings. The same goes for a repository you rename.

If connecting fails

Tracewell says	What to do
An owner of the organization has to install the app	You aren’t an owner, so GitHub only sent the owners a request. Ask an owner to connect GitHub.
The installation grants more than read access	Someone changed the app’s permissions at GitHub. Uninstall and connect again.
Your GitHub account can’t access this installation	Sign in to GitHub with an account in the organization, or ask an owner to connect it.

Remove Tracewell’s access

In your organization’s Settings, open GitHub Apps, select Configure next to Tracewell and then Uninstall. Tracewell can no longer read any of the organization’s repositories.