Vaubaan Gateway
Docs menu

Connect GitHub

An account of GitHub is connected once, on the instance, by a person who then gives missions access to its resources; the agent never receives the credential. Repositories, branches, files, pull requests, issues, releases and workflows of the GitHub App installation.

One account is one installation of your company's GitHub App on an organisation, or a fine-grained personal access token; one resource is one repository. A mission picks repositories and the permissions it holds on them. GitHub has no environment label: protected branches (main, master, release-*) and working branches (feature/*, fix/*, …) are told apart by two different permissions.

Permissions, presets and tools of this service: GitHub plugin.

How to connect

On the instance: Accounts → Connect an account, then pick the service. A company app, when the service needs one, is registered once by an administrator under Settings → Administration → Company apps, or set in the configuration (providers.<id>.*, see configuration keys). Every instance registers its own app: this gateway never uses an app shared with another one.

The usual way: by installing your company's app on your account at the service

An administrator creates the company app from the instance: Settings → Administration → Company apps, then "Create the app". The app's id, key and secrets come back stored encrypted; nothing to copy.

What the administrator enters for the company app:

  • GitHub App ID: Numeric App ID shown on the App settings page (Settings → Developer settings → GitHub Apps).
  • GitHub App private key (PEM) (secret): Generate a private key on the App settings page and paste the PEM (PKCS#1 or PKCS#8).
  • GitHub App slug: The URL slug of the App (https://github.com/apps/\&lt;slug\>) ; used to build the installation link.
  • GitHub App client ID: Client ID shown on the App settings page (not the App ID). The App must have "Request user authorization (OAuth) during installation" enabled.
  • GitHub App client secret (secret): Generate a client secret on the App settings page. Used only to check that the person who installs the App has access to the installation.

Another way: with a fine-grained personal access token pasted by hand

  1. Sign in to GitHub as the account the agents will act as.
  2. Open Settings, Developer settings, Personal access tokens, Fine-grained tokens, then Generate new token.
  3. Choose the organisation as resource owner, and only the repositories the missions need.
  4. Tick the permissions below; GitHub adds Metadata (read) by itself.
  5. Generate the token, copy it, and paste it here. GitHub shows it once.

Where: https://github.com/settings/personal-access-tokens

Permissions to grant at the service, and no more:

  • Metadata: read
  • Contents: read
  • Contents: read-write
  • Pull requests: read
  • Pull requests: read-write
  • Issues: read
  • Issues: read-write
  • Actions: read
  • Administration: read
  • Administration: read-write
  • Workflows: read-write

Recommended expiry: 90 days.

What the connect page asks:

  • Fine-grained personal access token (secret): A classic token (ghp_…) is refused: it reaches every repository of its account.

Not available when connected this way:

  • github__mint_install_token: needs the GitHub App: only an App mints the short-lived installation token this tool hands to git; ask an administrator to register your company's GitHub App, then connect the account through it.

The service's documentation: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

Disconnecting

Uninstall your company's GitHub App from the organisation, in the organisation's settings under GitHub Apps, once no other account of this gateway uses that installation. The gateway never uninstalls it: one installation may serve several accounts.

Registration notes from the plugin

From the plugin's README, written for the people who register the app or create the token.

Credential: the company's GitHub App

  1. Create the App from the gateway (once, by an administrator): Settings → Administration → Company apps → GitHub. Choose the owner (an organisation, or your own account), keep or change the name (Vaubaan &lt;host> by default) and the permissions — by default what the tools need; Contents write, Administration and Workflows are marked sensitive and can be withheld, and the page says which tools stop without each. The gateway posts GitHub's App manifest (private App, user authorization on install, the callback below, no webhook); GitHub shows the App and asks you to confirm, then sends you back; the gateway exchanges the one-hour code for the App's id, key and secrets and stores them encrypted. Nothing to copy. Then "Install it on your repositories" is connecting an account (step 3). The App belongs to you: every gateway has its own, never a shared one (ADR company-app-created-from-a-manifest).

    Or register it by hand ("Enter an app registered by hand" on the same page): GitHub → Settings → Developer settings → GitHub Apps → New GitHub App. Permissions the tools need: Contents (read & write), Pull requests (read & write), Issues (read & write), Metadata (read), Actions (read), Administration (read & write, for branch protection), Workflows (read & write, for pushes touching .github/workflows/). Generate a private key and a client secret. Under "Identifying and authorizing users", tick Request user authorization (OAuth) during installation and set the Callback URL to the gateway's connection callback (<public_url>/connections/callback/github, shown in Settings → Administration → Company apps). With that box ticked GitHub offers no setup URL: the callback URL receives both code and installation_id. Keep "Expire user authorization tokens" on.

  2. By hand only: configure the instance with the five app-config keys the spec declares: app_id, private_key (PEM, PKCS#1 or PKCS#8; a one-line PEM with literal \n is accepted), app_slug, client_id (the App's client ID, not its App ID) and client_secret. Missing keys leave the service unavailable in "Connect an account", which says why.

  3. Connect: the host redirects the user to https://github.com/apps/<app_slug>/installations/new. On the callback it exchanges code for a user access token (POST https://github.com/login/oauth/access_token), checks that installation_id is among GET /user/installations for that token, drops the token, and only then stores the installation id encrypted as the connection's secret. An installation the installing GitHub account cannot reach is refused and audited. All of this is declared in githubCredential.userVerification and run by the host: the plugin never sees the client secret or the user token, sees the private key only in ctx.appConfig, and never reads process.env.

  4. Resources: discoverResources lists the installation's repositories (GET /installation/repositories, 100 per page, up to 10 pages) as owner/repo resources with default_branch, private, archived in metadata. The owner labels environments later.

At call time the plugin mints a fresh installation token (JWT RS256, 9 min → token, 1 h) scoped to the repository the call names; search tools get an installation-wide token. github__mint_install_token returns a token scoped to the mission's repositories with the clone (contents:read) or push (contents, pull_requests, workflows: write; metadata: read) permission set — that token leaves the gateway's perimeter.

Credential, the other way: a fine-grained personal access token

When no GitHub App is registered — or when a person prefers it — an account is connected with a fine-grained personal access token pasted by hand (githubTokenCredential, src/token.ts, declared in alternativeCredentials). Often a shared service account: the gateway still decides every call, and Activity says who made it.

  1. At GitHub, signed in as the account the agents will act as: Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token. Choose the organisation as resource owner, only the repositories the missions need, an expiry (90 days recommended), and the permissions the connect page lists, derived from guide.permissions (Contents, Pull requests, Issues, Actions, Workflows, Administration; Metadata read is added by GitHub).
  2. Paste it on "Connect a GitHub account" ("Use a token instead" when the App is registered). A classic token (ghp_) is refused: it reaches every repository of its account.
  3. The gateway checks it (GET /user; the expiry header when GitHub sends it), lists the repositories it reaches (GET /user/repos), and seals it. Every API tool sends it as the bearer.

github__mint_install_token needs the App (it hands out an installation token): on a token account it is not listed and is refused before the budget. A token GitHub rejects (expired, deleted) turns the account "Needs reconnecting". Removing the account deletes nothing at GitHub: delete the token on the fine-grained tokens page. ADR token-connections-beside-the-integration-app.

Last changed 2026-10-16. This page as Markdown: /docs/providers/github.md