Connect GitHub Issues

Connect the issues of a GitHub repository with a fine-grained token that may change issues and nothing else.

In short

Connect GitHub Issues once for the whole organization. Each board then keeps its cards in step with the issues of one repository: titles, descriptions, open or closed, and labels. It is its own connection, so the code host's token stays read-only.

Before you start

• Who: someone who may manage the organization's connections, and the repository's admin to add the webhook.
• Plan: work tracker connections come with a paid plan, and the 14-day Business trial has them.
• First: a fine-grained token for the repository with Issues (Read and write) and Metadata (Read) - nothing else. A classic token is refused: it can also change code.

Sign in

1. Press "Open the token page". GitHub opens a new fine-grained token with Issues and Metadata chosen; pick the repository and press Generate.
2. Paste it into "Token" and type the repository into "A project to check with", such as acme/payments-api.
3. Press "Check this step". GitHub does not say what a fine-grained token may do, so the step passes with a reminder to keep it to issues.

Webhook

1. Press "Make the address and secret". Copy each - the secret is shown only now.
2. In the repository open Settings, Webhooks, Add webhook. Paste the address as the Payload URL, choose application/json and paste the secret.
3. Choose Let me select individual events: Issues. Then Add webhook.
4. Change an issue to send a first delivery.

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 Boards.
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" 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.