Connect GitHub

A GitHub connection lets workflows open and update issues, create and merge pull requests, commit and read files, publish releases and run GitHub Actions workflows — and start a run when something happens in a repository. It connects with a personal access token that you make in GitHub. Everything the steps do is done as the person who made the token.

Who can do this

• In Bizomate: workspace Admins and Editors, on every plan — GitHub is not a premium connection. Viewers see the connection but cannot add or change it.
• In GitHub: anyone can make a token for their own account. It reaches only what that account can reach. GitHub triggers also need the account to be an admin of the repository, because they add a webhook to it.

Before you start

Decide which kind of token to make:

• Fine-grained (starts github_pat_) — limited to the repositories you choose, with only the permissions you tick. GitHub recommends it, and some organisations allow only this kind.
• Classic (starts ghp_) — reaches every repository your account can, with broad scopes. Use it when an organisation's repositories cannot be reached with a fine-grained token.

Permissions each step needs

Tick what the steps you will use need. For a fine-grained token these are under Repository permissions; Metadata: Read-only is always included.

Steps

In GitHub, make a fine-grained token:

1. Sign in to GitHub. Select your profile picture at the top right, then Settings.
2. At the bottom of the menu on the left, select Developer settings.
3. Select Personal access tokens, then Fine-grained tokens, then Generate new token.
4. In Token name, type a name — for example Bizomate.
5. In Resource owner, choose your account, or the organisation that owns the repositories — for example consulace.
6. In Expiration, choose how long it lasts, and note the date — Bizomate can remind you before it ends.
7. Under Repository access, select Only select repositories and choose them — for example consulace/billing-service. Or All repositories.
8. Under Permissions, add the repository permissions from the table above, each set to Read and write where the table says so.
9. Select Generate token. Copy the token — it starts github_pat_. GitHub shows it only once.

Or make a classic token:

1. In Developer settings, select Personal access tokens, then Tokens (classic).
2. Select Generate new token, then Generate new token (classic).
3. In Note, type Bizomate, and choose an Expiration.
4. Tick repo. Tick workflow too if a step will change files under .github/workflows.
5. Select Generate token, and copy it — it starts ghp_.
6. If the organisation uses single sign-on, select Configure SSO beside the token and Authorize it for the organisation.

In Bizomate, add the connection:

1. Select Connections in the bar at the top, then + Add connection.
2. Under Developer Tools, select GitHub. The window opens on Personal access token, and says so under the name.
3. In Connection name, type a name — for example Consulace GitHub.
4. Paste the token in Personal access token — placeholder github_pat_… or ghp_…. Made in GitHub under Settings › Developer settings › Personal access tokens — fine-grained or classic. Give it the repositories and permissions its steps use. Stored encrypted; never shown again.
5. Optional: in This token expires on · optional, choose the token's expiry date — If the service gave the token an end date. The workspace’s admins are reminded 30, 7 and 1 days before.
6. Leave Test the connection before saving ticked. Bizomate asks GitHub who the token belongs to before keeping it.
7. Select Save connection. The button reads Testing while GitHub is asked.

The toast "Connection added" says "“Consulace GitHub” is ready. Every workflow in this workspace can use it."

What happens next

• The connection appears under Developer Tools. Its panel shows Test, Revoke and the masked token's ending — never the token.
• Test answers with the account and how many repositories the token reaches — for example "Reached @rohan-mehta · 3 repositories". From 100 repositories it reads "100+".
• GitHub steps and triggers list it under Connection. Their Repository list shows the token's repositories as owner/name, each marked Private or Public — for example consulace/billing-service · Private.

Good to know

• The token is tried before it is saved. A token GitHub refuses is never kept.
• The Repository list shows the 100 repositories updated most recently. For another, select Use a value above the list and type it as owner/name — consulace/billing-service.
• Tokens end. A token stops working on the expiry date you chose, and every GitHub step then fails with "Bad credentials". With the date in This token expires on, the connection turns amber 30 days before, the workspace's admins are reminded 30, 7 and 1 days before, and its panel offers Replace token. Make a new token before then, and replace it as below.
• To replace the token — after it ends, or after you regenerate it in GitHub — open the connection's panel and select Replace token, paste the new token and select Replace token. The old one is used until then, so no workflow fails in between. Once a date you entered has passed, the button reads Reconnect instead. The toast says "Token replaced".
• Adding a permission to a fine-grained token later keeps the same token. Nothing changes in Bizomate.
• An organisation may need to approve a fine-grained token before it reaches the organisation's repositories. Until an owner approves it, its repositories are missing from the list.
• Signing in with GitHub instead of a token is not offered yet; the token is the only way to connect.

If something goes wrong

Related

• Create, update or find GitHub issues
• Start a workflow from GitHub events
• Testing a connection
• Revoking or deleting a connection
• Connecting a service, and what we keep