GitHub¶

The github plugin connects Imbi to GitHub. One plugin serves github.com, GitHub Enterprise Cloud (GHEC) tenants, and GitHub Enterprise Server (GHES) appliances. Make one integration for each GitHub host.

It can do these things:

• Connect users to GitHub, and sign users in to Imbi.
• Read refs and commits, cut tags and releases, and create GitHub deployments.
• Create, rename, archive, transfer, and delete the repository of a project.
• Record commit, tag, and pull request history from webhooks.
• Check the repository link and the repository homepage in the Doctor.
• Issue GitHub App tokens to agent tasks through the github_app secret provider, which you configure in Admin, Secrets (see Secrets).
• Read a public github.com repository with no credentials, for an agent plugin marketplace.

Capabilities¶

An on-demand pull request sync also removes the project's open pull requests that the repository no longer lists, such as one filed under the project from another repository. Closed and merged pull requests are kept. It only does this when the project's repository link names the repository and the listing was complete, and it logs each pull request it removes.

Configuration¶

Options¶

Identity capability options¶

Deployment capability options¶

To send more workflow inputs for each environment, set the environment payloads of the assignment. See Assignments.

Lifecycle capability options¶

Credentials¶

All credentials are optional. Set the credentials for the features that you use. See Setup choices.

Setup choices¶

Each feature uses one of three credentials.

When both a token and GitHub App credentials are set, Imbi uses the token.

User identity¶

Each user connects GitHub at Settings > Connections. Imbi then calls GitHub with the token of that user. The flow is the OAuth web flow. Use the client ID and the client secret of a GitHub OAuth App or of a GitHub App.

Register the callback URL from the identity capability row of the integration page with GitHub. See Identity connections. If the provider returns a refresh token, Imbi refreshes the user token.

GitHub App¶

Imbi signs a JWT with the App private key and gets a short-lived installation token. It keeps the token in memory until shortly before it expires. No long-lived token is stored. If installation_id is empty, Imbi asks GitHub for the installation of each repository.

Each operation asks only for the permissions that it needs. Give the App the permissions of the features that you use:

Install the App on each repository that Imbi must read.

Token¶

A token works for all service features. The scope of a token is fixed when you make it. Imbi cannot reduce it.

The lifecycle capability uses the identity token of the acting user, or access_token. It never uses GitHub App credentials. Repository create, archive, and transfer need admin access to the repository. A transfer also needs admin access to the target organization.

Repository link¶

Each project links to one repository through the EXISTS_IN edge. See Project links to integrations. The GitHub plugin writes these values:

Webhook actions¶

These actions use the GitHub App or the token. They do not use a user identity. Imbi publishes the rows to Iggy, and the ClickHouse sink writes them to the commits, tags, pull_requests, pull_request_review_requests, and pull_request_reviews tables.

sync_pull_requests records the opened, closed, reopened, synchronize, review_requested, and review_request_removed actions. sync_pull_request_reviews records submitted, edited, and dismissed. For reviewers to show on the Open Pull Requests report, the GitHub webhook or App must send Pull request reviews events, and a webhook rule must run github#sync_pull_request_reviews on them. If a rule filter limits the pull_request actions, add the two review request actions.

Use the rule filter to select branches and tags. The webhook body is under payload. For example: payload.ref == "refs/heads/main" or payload.ref.startsWith("refs/tags/"). See Webhook filter expressions.

Each action has a handler configuration. The defaults fit the GitHub webhook body. These are the fields:

On the webhook, set the identifier selector to the repository ID, for example /repository/id. imbi-gateway uses it to find the project. To make the webhook, see Webhooks and Gateway.

Lifecycle¶

A failed lifecycle call does not stop or undo the change in Imbi.

Doctor checks¶

identifier-verified¶

The github_app secret provider issues GitHub tokens to agent tasks only for a repository ID that the plugin verified. An edge that a user made or edited by hand is not verified. The fix reads the repository from GitHub and writes the edge again, which verifies it. See Secrets.

homepage-url-match¶

The expected homepage is the Imbi page of the project. Imbi builds it from IMBI_UI_URL. The fix sends PATCH /repos/{owner}/{repo} with the new homepage. It is the only GitHub Doctor fix that writes to GitHub. The other fixes write to Imbi only. The credential must be able to change the repository settings.

The Doctor uses the identity of the acting user first. If there is none, it uses the GitHub App or the token.

Known limits¶

• One integration serves one GitHub host. Make a second integration for a second host.
• The lifecycle capability cannot use GitHub App credentials.
• Unarchive does not move a repository back to its first organization. Imbi does not record that organization.
• The ref list of a repository is limited to 1000 branches and tags.