Integrations
The Integrations settings: install the GitHub App on an organisation or an account, read what it was granted, sync it after a change at GitHub, forget it, and find where Telegram and webhooks are set up.
By the end of this page your team will have the GitHub App installed on the organisation or the account that owns its repositories, you will read what the installation was granted and when it was last synced, and you will know how to refresh it after a change at GitHub and how to let it go. Once it is in, every project picks its repositories from it on its Code pages, developers open branches from items, and the App's own webhook carries every repository's pushes and pull requests with no secret to paste per repository.
An installation is one GitHub App installed on one organisation or one personal account. It belongs to the team that installed it: the account it sits on, whether it reaches all of the account's repositories or a chosen few, the permissions it holds, the events it hears, who connected it and when, and whether it still stands. A team may hold several, one per account.
Before you begin
| To | You need |
|---|---|
| Open the Integrations settings | To be a member of the team; a client guest never reaches the settings. |
| Install, sync or forget the App | integration:manage; the administrators and the team's owner have it by default. |
| Finish the installation at GitHub | To own the organisation or the account at GitHub, or to be allowed to request an installation that an owner then approves. |
| Pick repositories onto a project | repository:create on the project; see Repositories. |
The page lives under Account Settings → Integrations. Everyone in the team reads it; only someone who manages integrations sees the buttons.
The App has to be set up on the workspace first
The GitHub App itself belongs to the workspace, not to a team: its operators register it at GitHub once and give the workspace its credentials. Until they have, the page says so, the Install on GitHub button stays away, and each repository is linked with a webhook of its own, as the GitHub page describes.
Install the GitHub App
- Press Install on GitHub. You are sent to the App's installation page at GitHub, carrying a one-time token that ties what you install to your team and to you. The token lasts fifteen minutes; start again from this page if GitHub kept you longer.
- At GitHub, choose the organisation or the account to install on, then choose All repositories or Only select repositories and tick the ones the team works in. Either choice can be widened later at GitHub.
- Press Install. GitHub brings you back to this page: the installation is recorded for your team, a green Live badge sits beside the account, and the toast says to pick its repositories from each project's Code pages.
An organisation that requires an owner's approval answers differently: GitHub records a request rather than an installation, the page says Installation requested, and nothing is connected until an owner approves the App at GitHub. Once they have, GitHub tells the workspace on its own and the installation appears here without another press; if it does not, press Install on GitHub again and GitHub completes what was approved.
A second account is installed the same way with Install on Another Account. An installation your team already holds is refreshed rather than doubled, and an installation another team made is refused with a word on the toast, so two teams never claim the same one.
Read an installation
Each installation is one card:
| On the card | What it shows |
|---|---|
| Account | The organisation or the account the App sits on, with its avatar, and whether it is an organisation or a person. |
| Badge | Live when the installation stands; Suspended at GitHub when the account suspended the App there; Forgotten when someone on this page let it go. |
| Selection | Whether the App reaches all repositories of the account or selected repositories, and the installation's id at GitHub. |
| Permissions | Every permission GitHub granted, read or write, as badges; contents: write is the one that lets branches be opened from items. None recorded yet means the installation has not been synced since GitHub last reported them. |
| Connected | When the installation was recorded and by whom. |
| Last synced | When the installation was last read from GitHub, by a sync here or by GitHub's own word. |
Sync an installation
Sync reads the installation from GitHub again and refreshes the account, the repository selection, the permissions and the events. Press it after granting the App new permissions at GitHub, after widening the repositories it reaches, or when a card's permissions read as not recorded. GitHub also tells the workspace on its own when the App's permissions are accepted or its repositories change, so most of the time the card is already current; a sync is the way to be sure.
Forget an installation
Forget marks the installation as no longer used by the team, after a confirmation. The repositories picked from it keep their rows and their history, and keep hearing the App's deliveries for as long as the App stays installed at GitHub; no branch is opened through it from then on, and no further repository is picked from it. The App itself stays installed at GitHub until someone uninstalls it there, which is the step that revokes its access. Uninstalling at GitHub without forgetting here is fine too: GitHub tells the workspace, and the card reads Forgotten on its own.
To use the account again later, install the App on it once more; a fresh installation at GitHub makes a fresh card here.
What GitHub tells the page on its own
The App's own webhook brings the installation's news without anyone pressing anything:
| GitHub reports | The card |
|---|---|
| The App uninstalled from the account | Reads Forgotten. |
| The App suspended, or resumed | Reads Suspended at GitHub, then Live again. |
| New permissions accepted | Shows the new permissions and a fresh Last synced. |
| Repositories added to or removed from it | Shows the selection and a fresh Last synced. |
What happens next
- Every project's Repositories tab gains Connect from GitHub, which lists what the installation reaches that the project has not registered yet; see Repositories.
- An item whose project has a repository picked from a live installation that may write its contents gains Create Branch in its Code panel; see Git linking.
- The branches, commits and pull requests of every picked repository arrive through the App's webhook and link themselves to the items whose keys they carry; see GitHub.
- Installing, syncing and forgetting are written to the team's activity log with who did it.
Telegram and webhooks
The two cards under the installations point to the other integrations, which live on their own pages: the Telegram bot is linked per person under Notifications and a project's group is set in its settings; outbound webhook endpoints that receive signed events for your pipelines and chat tools have their own settings page.
Heimdall on this page
Heimdall reads the installations and the repositories they offer, so it can say which account the team's App sits on and whether a repository can take a branch; installing, syncing and forgetting stay with you, and no agent tool does them.
From the API and MCP
Git connections API
List and read the team's installations, sync and forget one, list what an installation offers a project, and register the picked repositories over REST.
create_branch
The one MCP tool that acts through an installation: a branch opened for an item in a repository picked from it.
Installing itself has no API: the one-time token and the return from GitHub need a person and a browser.
Permissions
| Action | Permission |
|---|---|
| Read the installations | Membership of the team; never a client guest |
| Install, sync or forget | integration:manage; administrators and the owner by default |
| Read, sync or forget over the API | integration:manage on the token |
| Pick repositories onto a project | repository:create on the project |
| Open a branch from an item | work-item:update on the project |
Frequently asked
Related
- GitHub: what arrives through the App and the webhook by hand as the alternative.
- Repositories: picking an installation's repositories onto a project.
- Git linking: branches opened from items and the links that follow.
- Webhooks: the outbound endpoints that receive the events Zuse Bifrost sends.
- Notifications: linking the Telegram bot to your account.
How is this guide?
Last updated on
Webhooks
Register an endpoint that receives signed event payloads, pick its events, rotate its secret, pause or test it, and read and replay the delivery log.
Projects
What a project is in Zuse Bifrost, the key that prefixes every reference in it, its lifecycle statuses and health, the client it is done for, and the pages that manage them.