GitHub App Runbook¶
This runbook gives one agent access to GitHub, from the start to the end:
GitHub, AWS, and Imbi. After the setup, the agent's runner can clone the
project repository, and the agent can push and open pull requests and
issues. The commits and pull requests show as <agent>[bot].
Imbi stores no GitHub token. For each request, imbi-api reads the App private key from AWS Secrets Manager and gets a new installation token from GitHub. The token covers one repository and one purpose, and lasts one hour at most.
This page gives the order and the values for each side. The Imbi screens have their own pages, linked from each step.
The examples use the agent reviewer, the App ID 1234, and the GitHub
host example.ghe.com. Use your own values.
How the parts connect¶
| Part | Where | What it holds |
|---|---|---|
| GitHub App | GitHub | The App ID and the permissions. The permissions are the upper limit of each token |
| Private key | GitHub, then AWS | The .pem file. imbi-api signs a JWT with it |
| Installation | GitHub | One for each GitHub organization. A token can only cover repositories of one installation |
| Secret | AWS Secrets Manager | The .pem text |
| Key binding | Imbi | A reference for the AWS secret, marked as a provider key. Only imbi-api reads it. No grant can give it to an agent |
| App binding | Imbi | The App ID and the reference of the key binding. It gets the tokens |
| Grants | Imbi | Which agents may use the App binding, for which purposes |
| Agent setting | Imbi | Which App binding the runner asks for |
The agent setting and the grants do different things. The setting tells the runner which binding to ask for. The grant decides if imbi-api allows the request. The agent needs both.
How a token is made¶
The runner asks for a token when a task starts, to clone the repository. The agent asks for a second token when it pushes or opens a pull request. The Step column gives the setup step that each message needs.
- imbi-api does all of the GitHub authentication. The private key goes from AWS to imbi-api and no further. The runner pod gets only short-lived tokens.
- The token for
github_writeis in the environment of one command only, and Imbi removes it from the command output. - The token covers only the repository that the GitHub integration
verified for the project. If the project's
EXISTS_INedge was made or edited by hand, the Doctor checkidentifier-verifiedfails and Imbi refuses the token.
Before you start¶
These parts are made one time for each Imbi organization, not for each agent. Check that they exist:
| Part | Where | See |
|---|---|---|
IAM role that imbi-api assumes, with the ExternalId imbi:<organization id> and read access to the secret prefix |
AWS | Secrets, Prepare AWS |
| An AWS Secrets Manager provider | Admin, Secrets, Providers | Secrets, Add a provider |
A github_app provider with the GitHub host |
Admin, Secrets, Providers | Agent Runners, Configure GitHub access |
Click Test on each provider row to check it.
The github_app provider accepts github.com, a <tenant>.ghe.com
host, or a GHES host that the operator lists in
IMBI_SECRETS_GITHUB_GHES_HOSTS.
Step 1: Create the GitHub App¶
In the GitHub organization that owns the App, open Settings, Developer settings, GitHub Apps, New GitHub App.
| Field | Value |
|---|---|
| GitHub App name | The agent name, for example reviewer. Commits show as reviewer[bot] |
| Homepage URL | Any URL, for example the Imbi page of the agent |
| Webhook | Clear Active. Imbi needs no events from this App |
| Repository permissions: Contents | Read and write |
| Repository permissions: Pull requests | Read and write |
| Repository permissions: Issues | Read and write |
| Repository permissions: Metadata | Read-only (GitHub adds it) |
| Where can this GitHub App be installed? | Any account. A private App can only be installed in the organization that owns it |
Click Create GitHub App. Copy the App ID from the App settings page.
Each token asks only for the permissions of its purpose. GitHub refuses a token with more permissions than the App has.
| Purpose | Token permissions |
|---|---|
workspace_checkout |
contents: read |
marketplace_fetch |
contents: read |
github_write |
contents: write, pull_requests: write, issues: write |
Step 2: Generate the private key¶
On the App settings page, under Private keys, click Generate a
private key. The browser downloads a .pem file. Keep it only until
step 4.
Step 3: Install the App¶
On the App settings page, click Install App. Select a GitHub organization, then All repositories or the repositories that the agent works in. Click Install. If the organization requires approval, an organization owner approves the install.
Do this for each GitHub organization that the agent works in.
You do not need the installation ID. Imbi finds the installation of each repository. The repositories of one token must all be in one installation.
To check, open the organization's Settings, GitHub Apps. The App is in the list.
Step 4: Store the key in AWS¶
In AWS Secrets Manager, click Store a new secret:
| Field | Value |
|---|---|
| Secret type | Other type of secret, Plaintext |
| Value | The full .pem text, with the BEGIN and END lines |
| Secret name | For example imbi/github/reviewer. Use a name that the IAM role can read |
| Encryption key | The default key, or a KMS key that the role can decrypt |
Then delete the local .pem file.
Step 5: Add the key binding¶
Open Admin, Secrets, Bindings and click New binding (see Secrets, Add a binding).
| Field | Value |
|---|---|
| Reference | ghe/reviewer_private_key. Use lower case letters, digits, and _ |
| Provider | The AWS Secrets Manager provider |
| Credential class | static |
| Secret ID | imbi/github/reviewer |
| Allowed fields | Empty |
| Provider key host | example.ghe.com |
| Provider key App id | 1234 |
Leave Consumers empty. The App binding does not exist yet. Do not add a grant for this binding.
Click Validate on the row to check that Imbi can read the AWS secret.
Step 6: Add the App binding¶
Click New binding again.
| Field | Value |
|---|---|
| Reference | ghe/reviewer |
| Provider | The github_app provider |
| Credential class | dynamic |
| App ID | 1234 |
| Installation ID | Empty, so that one binding works in each GitHub organization |
| Private key | secret://ghe/reviewer_private_key |
| Repositories | Empty. Only marketplace_fetch uses this list. See Agents, Plugin marketplaces |
| Allowed delivery modes | file_descriptor and environment |
| Description | What the token is for. The agent sees this text |
Then edit the key binding ghe/reviewer_private_key. Under
Consumers, select ghe/reviewer and save.
The order matters. The App binding must name an existing key binding, and the Consumers list shows only existing App bindings.
Click Validate on the App binding row.
Step 7: Grant the runner purposes¶
The runner uses these tokens to clone the project repository and to fetch plugins. The agent never sees them. The agent must exist before a grant can name it, so save the agent first.
Open Admin, Secrets, Grants and click New grant.
| Field | Value |
|---|---|
| Agents | reviewer |
| Bindings | ghe/reviewer |
| Purposes | workspace_checkout, marketplace_fetch |
| Delivery modes | file_descriptor only |
| Projects | All, or the selected projects |
Step 8: Grant the write purpose¶
The agent uses this token to push and to open pull requests and issues
with run_with_secret.
| Field | Value |
|---|---|
| Agents | reviewer |
| Bindings | ghe/reviewer |
| Purposes | github_write |
| Delivery modes | environment only |
| Projects | All, or the selected projects |
Keep the grants of steps 7 and 8 separate. A grant allows each of its
purposes with each of its delivery modes, and exactly one grant must
allow each request. With no match, Imbi refuses the request with
no_grant. With two matches, it refuses with ambiguous_grants.
Step 9: Select the App binding on the agent¶
Open Agents, the agent, Edit, then the Access tab. Select
ghe/reviewer as the GitHub App and save. See
Agents, Access.
The tab shows a row for workspace_checkout, github_write, and
marketplace_fetch. Each row shows a check when a grant allows it.
You can also do this step right after step 6. Then click Grant on each row that has no check. Imbi adds the purpose to the agent's grant that has the same binding and delivery mode, or makes a new grant. The result is the grants of steps 7 and 8.
Check¶
Run a task on a project whose GitHub repository the agent can reach. Open Admin, Secrets, Resolutions to see the token reads, and Audit to see a refused request and its reason.
| Reason | Fix |
|---|---|
installation_not_found |
Install the App in the GitHub organization of the repository (step 3) |
permission_or_repository_not_granted |
Give the App the permission (step 1), or add the repository to the installation (step 3) |
no_grant |
Check the grant's agents, binding, purposes, delivery modes, and projects (steps 7 and 8) |
ambiguous_grants |
Remove the overlap, so that one grant matches (steps 7 and 8) |
repositories_span_installations |
Use repositories of one GitHub organization for each task, or separate bindings |
If Imbi refuses the token for the project repository, run the project's
Doctor and apply the identifier-verified fix.
Use one App for more than one agent¶
Nothing in Imbi requires one App for each agent. A grant can name more
than one agent, so other agents can use ghe/reviewer. Their commits and
pull requests then show as reviewer[bot].