GitHub App authentication

canette can authenticate with GitHub as a GitHub App instead of using personal access tokens. GitHub Apps use short-lived tokens generated on demand — no long-lived secrets are stored per user — and work as a machine identity with an explicitly-granted permission scope.

Two modesCopy Anchor Link

Both modes can be active at the same time — a team can use either the system credential or their own installation when configuring an app. You can start with the system credential and add the per-team wizard later by setting publicLink in Helm and the Setup URL in the GitHub App settings.

Required GitHub App permissionsCopy Anchor Link

When creating the GitHub App, grant only these permissions:

SetupCopy Anchor Link

Step 1 — Create the GitHub AppCopy Anchor Link

1. Go to your GitHub organisation settings → Developer settings → GitHub Apps → New GitHub App (or visit your personal settings if not using an org).
2. Fill in the required fields:
   • GitHub App name: e.g. canette-yourorg
   • Homepage URL: your canette URL, e.g. https://canette.example.com
   • Webhook: leave disabled — canette manages webhooks separately
3. Under Repository permissions, set Contents: Read-only and Webhooks: Read and write.
4. Under Where can this GitHub App be installed?: choose Any account (allows teams to install on their own accounts/orgs) or Only on this account if you only need system credential mode.
5. Click Create GitHub App.
6. Note the App ID shown at the top of the app settings page.
7. Note the Public link — shown in the GitHub App settings as a full URL (https://github.com/apps/{slug}).
8. (Per-team mode) Scroll to Post installation and set the Setup URL to https://canette.example.com/api/v1/github-app/callback. Optionally check "Redirect on update" so re-installations also redirect back. Do not use the Callback URL field — that is for OAuth user authorization and is not needed here.

Step 2 — Generate a private keyCopy Anchor Link

On the GitHub App settings page, scroll to Private keys and click Generate a private key. A .pem file is downloaded. Keep it safe.

Step 3 — Helm configurationCopy Anchor Link

Before filling in values, decide which mode fits your deployment — you can also configure both together (see below).

Choose system credential mode (set installationId) if a small, trusted group of teams shares the same repos, or if you — the admin — want to control exactly which repositories canette can access. One installation, one place to manage access; teams don't do anything extra.

Choose per-team installation mode (leave installationId empty, set publicLink) if teams belong to different GitHub orgs/accounts, or you don't want every team implicitly able to deploy from every repo the admin's installation can see. Each team connects their own GitHub account or org via the in-app wizard, so access stays scoped to what that team explicitly installed the App on.

System credential mode (admin installs once)Copy Anchor Link

api:
  githubApp:
    appId: "123456"              # App ID from GitHub App settings
    installationId: "12345678"   # Installation ID (see below)
    privateKey: |
      -----BEGIN RSA PRIVATE KEY-----
      MIIEowIBAAKCAQEA...
      -----END RSA PRIVATE KEY-----

To find the Installation ID: click Install App in the left sidebar of the GitHub App settings, choose an org, then look at the URL after installation:

https://github.com/organizations/<org>/settings/installations/12345678

The number at the end is the Installation ID.

Per-team installation mode (users connect their own accounts)Copy Anchor Link

api:
  githubApp:
    appId: "123456"              # App ID from GitHub App settings
    publicLink: "https://github.com/apps/canette-yourorg"  # "Public link" from GitHub App settings
    privateKey: |
      -----BEGIN RSA PRIVATE KEY-----
      MIIEowIBAAKCAQEA...
      -----END RSA PRIVATE KEY-----

No installationId is needed — users install the app themselves. Remember to set the Setup URL in your GitHub App settings (see Step 1 above).

Both modes togetherCopy Anchor Link

api:
  githubApp:
    appId: "123456"
    installationId: "12345678"
    publicLink: "https://github.com/apps/canette-yourorg"
    privateKey: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----

If you prefer to keep the private key in a separate Kubernetes Secret, use privateKeySecretRef instead of privateKey:

api:
  githubApp:
    appId: "123456"
    publicLink: "https://github.com/apps/canette-yourorg"
    privateKeySecretRef:
      name: my-github-app-secret
      key: private-key

Run helm upgrade to apply the changes. Both the API and builder pods receive the configuration as environment variables.

Using the GitHub App credentialCopy Anchor Link

System credentialCopy Anchor Link

Once configured, a GitHub App (system) entry appears in the GitHub App section of every team's credentials page. Select it when adding an app in canette to use it for git access.

Per-team installation wizardCopy Anchor Link

When publicLink is configured, users see a "Connect GitHub Account or Org" button in the GitHub App section of their team settings:

1. Click Connect GitHub Account or Org.
2. GitHub opens and asks which account or organisation to install on, and whether to grant access to all repositories or specific ones.
3. After approval, canette stores the installation and it appears in the team's credential list.
4. Team members can then select it when configuring an app.

Installations are team-scoped and persist independently of who added them.

How tokens workCopy Anchor Link

When a build is triggered or a webhook is registered, canette generates a fresh installation token (1-hour lifetime) on demand using the private key. The token is used immediately as x-access-token in git clone URLs or as an API bearer token, and is never stored anywhere.

Rotating the private keyCopy Anchor Link

1. Generate a new private key from the GitHub App settings.
2. Update your Helm values (or the referenced Kubernetes Secret) with the new key.
3. Run helm upgrade. The old key can be deleted from the GitHub App settings afterwards.

TroubleshootingCopy Anchor Link

"Connect GitHub Account or Org" button is not visible GITHUB_APP_PUBLIC_LINK is not set in the API configuration. Set api.githubApp.publicLink in Helm values and run helm upgrade.

System credential does not appear in the credentials list Both api.githubApp.appId and api.githubApp.installationId must be set. If only appId is configured (per-team mode only), no system credential is created.

GitHub App not configured error GITHUB_APP_ID or the private key is missing. Check the API pod's environment variables.

GitHub App token exchange failed (401) The private key does not match the configured App ID, or the key has been revoked. Regenerate a private key from the GitHub App settings and update Helm values.

GitHub App token exchange failed (404) or build fails with a per-team credential The installation has been suspended or uninstalled on GitHub. The team member needs to reconnect by going to the team's GitHub App settings and clicking Connect again.

Clone succeeds but webhook auto-registration fails Ensure the GitHub App has Webhooks: Read & Write permission. If recently added, reinstall the app on the organisation for the updated permission to take effect.