Connect GitHub with the GitHub App

Install {{brand}}'s GitHub App on the repositories you choose. It only reads, and no personal token is kept.

In short

Connect GitHub once for the whole organization. {{brand}}'s GitHub App reads only the repositories you choose and never writes. Boards, designs and API projects then use the connection.

Before you start

• Who: someone who may manage the organization's connections - owners and admins have it by default.
• Plan: every plan keeps one code host; Business keeps 10 connections and Enterprise any number.
• First: you can install apps on the GitHub account or organization - usually its owner - and you know which repositories to share.

Install the app

1. Open your organization, then Settings › "Connections", and press "Connect a code host".
2. Choose "GitHub App". The wizard opens; each step is checked before the next one opens.
3. Read what the app may do and press "Next".
4. Press "Install the GitHub App". In GitHub choose the account, then All repositories or Only select repositories, and press Install.
5. GitHub brings you back to the wizard. Press "Check this step": it finds the installation and checks it can only read.

No GitHub App here? When this installation of {{brand}} has no GitHub App set up, the wizard says so. Use /help/settings/connect-github instead.

Check and use

1. Press "Run the full check". Every step should say Passed; a step that failed names what to change.
2. Under "Where will you use it?" tick the modules that will use it - Boards, Designer and API Tester.
3. Optional: under "Only these teams" tick the teams that may pick it. Leave it empty for everyone who may use those modules.
4. Check the "Name" - boards, designs and projects show it - and press "Finish". The connection shows under "Connections" with its health.

If a step fails

• A failed step names its code, what it means and what to change. The code's section of /help/settings/fix-a-company-connection says more.
• Change what the step says and press "Check again". The next step opens only when this one passes.
• Closing the wizard keeps every step that passed. Press "Continue setup" on the connection's row to go on where you stopped.

Good to know

• The app's tokens last an hour and are made when they are needed; {{brand}} keeps none.
• Push and pull request events come with the app: there is no webhook to set up.
• To share more repositories later, change the installation in GitHub: Settings, Applications, Configure.

• A connection's row shows its health, its last delivery and "Where used".
• "Deliveries" lists what the webhook address received in the last 30 days and where each delivery went.
• "Disconnect" first lists every board, design and project that would stop using it.
• Nobody else pastes a token: boards, designs and API projects pick this connection.

Related

• /help/settings/connect-github
• /help/settings/fix-a-company-connection
• /help/settings/webhooks-and-site-ownership