# GitHub App installation credentials

> Install the Constal GitHub App or bring your own App for unattended agent automation.

Use GitHub App installation authority for background repository and organization automation. The Constal-managed App is available to every tenant; GitHub returns its installation through the Credential Provider callback instead of asking the operator to copy identifiers.

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

Choose whether users should install the Constal-managed App or a GitHub App owned and branded by your tenant. In either case, decide the minimum repository and organization permissions the agent needs before asking an organization owner to authorize access.

## Install the Constal GitHub App {#constal-app}

1. Select **Create credential** and choose **Constal GitHub App**, or select **Connect GitHub** from your profile.
2. Choose the GitHub account or organization.
3. Select the repositories the agent may access and approve the requested permissions.
4. Return to Constal. **Create credential** activates the installation Credential. **Connect GitHub** on the profile page also creates its `github-user` principal binding.

Do not enter an installation ID. GitHub supplies it as callback evidence. Repository and permission fields are optional reductions within the repositories and permissions approved in GitHub.

## Bring your own GitHub App {#bring-your-own}

Use the catalog package when downstream customers should install an App owned and branded by your tenant.

- Create a GitHub App under the tenant's GitHub account or organization.
- Choose only the repository and organization permissions the agent needs.
- Generate and download one private key.
- Record the App Client ID and App slug from `github.com/apps/<slug>`.
- Set the App setup URL to `https://platform.constal.ai/v1/credential-interactions/callback` and enable redirect on update.

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 and App slug.
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. Optionally restrict repository names, repository IDs, or permissions under **Optional settings**.
4. Select **Continue**, choose the GitHub account or organization, and approve repository access.
5. Return to Constal. The callback completes and activates 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 callback missing:** verify the App setup URL exactly matches the shared Constal callback and redirect-on-update is enabled.
- **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).