Connect GitHub

• You are an owner of the Groundcrew workspace.
• You can install GitHub Apps on the account that owns the repositories: your personal account, or an organization where you are an owner (or an organization owner approves the request).
• You know which repositories Groundcrew should work with. You can change the list at any time.

1. Open the picker

   In Groundcrew, open Connections and choose Pick repositories on the GitHub card.

2. Install on GitHub

   Choose Install the GitHub App, or open github.com/apps/groundcrew-app and choose Install. Pick your personal account or the organization.

3. Choose repositories

   Choose Only select repositories and pick the ones Groundcrew should work with. Installing on all repositories works too, but selecting is safer.

The Groundcrew GitHub App is installed on many accounts. A workspace can only use installations that one of its owners has shown they can reach on GitHub. Back in Groundcrew, choose Find my installations:

1. GitHub asks you to authorize Groundcrew. This confirms who you are on GitHub.
2. Groundcrew asks GitHub which installations of its app you can reach, keeps that list for this workspace, and drops the one-time GitHub token at once.
3. You come back to the Connections page with the repository picker open.

The picker lists each installation you can reach and its repositories (private ones have a lock). Tick the repositories this workspace should use and choose Link repositories. Then run discovery from the Connections page.

A repository has to be both shared with the app on GitHub and linked here. Sharing decides what Groundcrew could read; linking decides what this workspace uses.

• Repository contents, read and write. Reads files to see how an app is built and deployed (Dockerfiles, workflows, infrastructure code) and to build it. Writes only to new branches named groundcrew/fix-* for fix pull requests you approved.
• Pull requests, read and write. Opens a fix pull request after you approve it, and follows its state. Groundcrew never merges a pull request and never pushes to your default branch.
• Actions, read. Reads workflow runs to link deploys to commits and to see when a merged fix was deployed.
• Metadata, read. Required by GitHub for every app.
• Email addresses, read (account permission). Used at sign-in to know which of your addresses GitHub verified, so invitations and accounts with the same address are matched.

Installation tokens expire after at most an hour, and Groundcrew asks GitHub for new ones as it needs them. We recommend branch protection on your default branch with a required review, so a fix pull request always gets a person's review before it merges.

• Find my installations shows none. GitHub only lists installations you can access. Check the app is installed on that account (in GitHub, Settings, Applications, or the organization's GitHub Apps). For an organization, you need to be a member with access to the installation; an organization owner may still need to approve your install request.
• The installation is there but has no repositories. The picker says no repositories are shared with the app on that account yet. Use Install the app on more repositories to add some on GitHub, then open the picker again.
• A repository is missing. It is not shared with the app. Add it in the app's settings on GitHub (Configure, Repository access).
• "This GitHub authorization expired or is not valid". More than 10 minutes passed, or the page was reloaded with an old link. Choose Find my installations again.
• "This GitHub authorization was started by someone else". You opened a link another person started. Start it yourself.
• The repositories are on another account. Choose Find installations on another account at the bottom of the picker.
• The connection shows as suspended or uninstalled. Someone suspended or uninstalled the app on GitHub. Groundcrew stops the connection at once. Install or unsuspend it, then link the repositories again.

To add or remove repositories, change them in the app's settings on GitHub and open the picker in Groundcrew again. A repository you remove on GitHub leaves the connection automatically.

To disconnect, remove the GitHub connection on the Connections page, then uninstall the app on GitHub (your settings, Applications, Installed GitHub Apps, or the organization's settings). Uninstalling revokes access at once. Pull requests Groundcrew opened stay on GitHub until you close them. See Delete data.