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

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

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

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 and Generating an installation access token.

Set up the provider

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

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

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

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

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

• 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

Read Scoped bindings and Credential lifecycle.