# GitHub App installation credentials

> Configure a tenant-owned GitHub App and mint short-lived installation tokens for unattended agents.

Use GitHub App installation authority for background repository and organization automation. The tenant brings its own GitHub App. Constal stores the App private key once and creates one managed Credential per GitHub installation or least-privilege repository selection.

## Before you begin {#before-you-begin}

- Create a GitHub App under the tenant's GitHub account or organization.
- Choose only the repository and organization permissions the agent needs.
- Install the App on the intended account and repositories.
- Generate and download one private key.
- Record the App Client ID and installation ID.

The Client ID identifies the App when generating its JWT. The private key signs that JWT. Do not use a user OAuth client secret for this provider.

GitHub references: [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app) and [Generating an installation access token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app).

## Set up the provider {#steps}

1. In **Credentials → Providers**, select **Add provider**.
2. Choose **GitHub App installation**.
3. Enter the GitHub App Client ID.
4. Paste or load the PEM private key.
5. Select **Set up provider**.

Constal stores the key as a separate encrypted bootstrap Credential. The provider can request it only through its declared `private-key` slot.

## Create an installation Credential {#create-credential}

1. Select **Create credential** and choose the installed GitHub App provider.
2. Name the Credential for the customer or installation.
3. Enter the installation ID.
4. Optionally restrict repository names, repository IDs, or permissions under **Optional settings**.
5. Create the Credential.

The provider signs a short-lived App JWT, requests an installation token from GitHub, verifies it against the installation repository endpoint, and schedules renewal before expiry.

## Bind it {#bind-it}

Use tenant scope for one internal installation. Use customer scope when one shared agent serves multiple downstream organizations:

```text
key github-token + customer Acme → credential/github-acme-installation
key github-token + customer Beta → credential/github-beta-installation
```

## Verify {#verify}

Confirm that the Credential is active, recent activity records a verified minted version, and the consuming GitHub Resource appears under **Where it is used**. Invoke one read-only repository operation before enabling write operations.

## Troubleshooting {#troubleshooting}

- **JWT or key invalid:** confirm the private key belongs to the App identified by the Client ID.
- **Installation not found:** use the installation ID from the installation settings URL or webhook payload.
- **Repository unavailable:** confirm the App installation includes that repository.
- **Permission denied:** add the required App permission and have the organization approve the updated installation.

## Next steps {#next-steps}

Read [Scoped bindings](/docs/credentials/scoped-bindings.md) and [Credential lifecycle](/docs/credentials/lifecycle.md).