# GitHub App authentication

> Authenticate a GitHub source code repository connection with an organization-owned GitHub App instead of a personal access token

---

Site [llms.txt](/llms.txt)

---

A GitHub source code repository connection authenticates with either a **Personal Access Token (PAT)** or a **GitHub App**. Both methods support reading (auto-import) and pushing, work with GitHub Cloud and self-hosted GitHub Enterprise Server, and are selected **per connection**. The same repository can therefore authenticate differently in different Cloud Management Platform (CMP) environments.

| Personal Access Token | GitHub App |
| --- | --- |
| A personal identity. The connection stores a read token, and each user pushes with their own token. | A non-personal, organization-owned identity that keeps working when people change teams or leave. |
| Best for **development environments**, where users author content and push it under their own GitHub identity. | Best for **staging, QA, and production**, as it refreshes promoted content without relying on an individual's token. |

In a typical promotion workflow, developers connect with PATs and push blueprints, actions, and other content to the repository. Each higher-level environment connects to the same repository with a GitHub App and refreshes the promoted content.

GitHub App connections can also push where a higher-level environment requires it, such as a pipeline that commits back. Grant the App **Contents: Read-only** for refresh-only environments, and **Read and write** only where CMP pushes.

## When to use GitHub App authentication

- Higher-level environments that refresh content and should not depend on one person's GitHub account.
- Private repositories that need an organization-owned identity surviving staff changes.
- Pushes governed by CMP permissions rather than by each user maintaining a personal write token.
- GitHub Enterprise Server deployments that require organization-managed credentials.

## Prerequisites

Create and install a GitHub App before configuring CMP.

1. In GitHub, go to **Settings** > **Developer settings** > **GitHub Apps** and select **New GitHub App**.
1. Under **Repository permissions**, set **Contents** to **Read-only** for refresh, or **Read and write** if CMP pushes to the repository.
1. Generate a **private key** on the App's settings page and download the `.pem` file.
1. **Install** the App on the organization, or on the specific repositories that CMP accesses.
1. Note the **App ID** from the App's settings page, under **General** > **App ID**. This is a number, not the Client ID.

<div class="alert alert-info" role="alert"><div class="h4 alert-heading" role="heading">An installation ID is not required</div>


CMP discovers the correct installation for each repository when it requests a token, so a single credential works across all repositories where the App is installed.
</div>


<div class="alert alert-danger" role="alert"><div class="h4 alert-heading" role="heading">Keep the private key secret</div>


Anyone with this key can authenticate as the App. CMP stores the key in an encrypted form and never displays it again after you save it.
</div>


## Add GitHub App credentials

Use this workflow to store a reusable GitHub App credential. Any number of connections that share the same organization's App can select it.

1. Go to **Admin** > **Source Code Repositories**.
1. Select the **GitHub App Credentials** tab, then select **New GitHub App Credential**.
1. Provide a **Name** to identify the credential when selecting it on a connection.
1. Provide the numeric **App ID**.
1. Paste the full contents of the `.pem` file into **Private Key (PEM)**, including the `-----BEGIN` and `-----END` lines.
1. Optionally provide an **API Base URL Override**. Leave this blank unless your GitHub Enterprise Server instance uses a non-standard API base.
1. Select **Create**.

To rotate a key, edit the credential and paste the new key material. Leaving **Private Key (PEM)** blank when editing keeps the stored key unchanged.

A credential cannot be deleted while any connection still uses it. The delete dialog lists the connections that reference it; change those connections to a different authentication method or credential first.

## Use GitHub App authentication on a connection

1. Create or edit a **GitHub Repository** source code repository connection. See [Integrate a remote source code repository](/docs/cmp/configure/integrations/source-code-repository/).
1. Set **Authentication Method** to **GitHub App**. The **Username** and **Password or Token** fields are replaced by the credential selector.
1. Select a **GitHub App Credential**.
1. Select **Create** or **Save**.

CMP validates the App credentials when it initializes the connection's local clone, which happens when you create the connection or change its **Repository URL**. An incorrect App ID or private key is reported at that point.

<div class="alert alert-info" role="alert"><div class="h4 alert-heading" role="heading">Personal tokens are ignored in GitHub App mode</div>


The connection's authentication method is authoritative, so a user does not need a personal push token to push through an App connection. Pushes authenticate as the App, while the git commit author remains the CMP user who initiated the push.
</div>


## GitHub Enterprise Server

The workflow for a self-hosted instance is identical to GitHub Cloud; only the API base URL differs. CMP derives the base URL from the repository host automatically, using `https://<your-ghes-host>/api/v3`.

Set **API Base URL Override** only if your instance uses a non-standard base. The override must be an `https://` URL, and its host must match either the connection's own repository host or `api.github.com`.

If your instance uses a self-signed certificate, add its CA certificate chain as described in [SSL root certificates](/docs/cmp/configure/access-and-security/security/ssl-root-certificates/). CMP uses that trust store for all outbound requests, including GitHub App API calls. TLS verification is always enforced for these calls.

Confirm that GitHub Apps are enabled on a supported GitHub Enterprise Server release.

## Permissions, attribution, and protected branches

- Pushes appear in GitHub as the **App identity**, not as the individual user, and the App's installation permissions apply uniformly. CMP permissions govern who can trigger a push.
- To allow the App to push to a **protected branch**, add the App to the branch ruleset's **bypass list** in GitHub. Classic branch protection cannot be bypassed by an App.
- Keep the CMP appliance clock synchronized using NTP. Each git operation mints a short-lived token signed with a 10-minute JSON Web Token, so significant clock skew causes authentication failures.

## Configure using the API

GitHub App authentication can also be configured through the CMP API. Both the `gitHubAppCredentials` and `sourceCodeRepos` endpoints require CMP admin privileges, and `privateKey` is write-only: it is accepted on create and update, but is never returned in a response.

Create a credential with `POST /api/v3/cmp/gitHubAppCredentials/`, then reference it from a connection with `POST /api/v3/cmp/sourceCodeRepos/`:

```json
{
  "type": "github",
  "label": "Platform Blueprints",
  "repoUrl": "https://github.com/Org/Repo",
  "authMethod": "GITHUB_APP",
  "githubAppCredentials": "/api/v3/cmp/gitHubAppCredentials/GAC-9f3ba1c2/"
}
```

A credential is required when `authMethod` is `GITHUB_APP`. Switching a connection back to `PAT` clears the credential reference automatically. On a `GET`, the credential is returned under `_links` as an href, so the configuration round-trips without exposing the private key.

For the full request and response schemas, see the API documentation on your CMP appliance. See also [REST API](/docs/cmp/developer-resources/rest-api/).

## Troubleshooting

| Symptom | Likely cause | Resolution |
| --- | --- | --- |
| GitHub rejected the App JWT (401) | Incorrect App ID or private key, or appliance clock skew | Verify the App ID and private key, and confirm NTP is running on the CMP appliance |
| The installation was not found (404) | The App is not installed on the repository's organization or account, or it was uninstalled | Install the App on the organization or repository that CMP targets |
| The installation may be suspended, or the App lacks permission (403) | Suspended installation, or missing Contents permission | Unsuspend the installation, then grant and re-approve Contents read or read and write access |
| A push to a protected branch is rejected | The App is not on the branch ruleset's bypass list | Add the App to the bypass list for the branch ruleset in GitHub |
| TLS errors against GitHub Enterprise Server | A self-signed certificate is not trusted | Add the CA certificate chain, as described in [SSL root certificates](/docs/cmp/configure/access-and-security/security/ssl-root-certificates/) |

## Non-personal authentication for GitLab

GitLab does not use GitHub Apps. To authenticate a GitLab connection with a non-personal identity, create a group or project access token in GitLab and provide it in the **Username** and **Password or Token** fields on the GitLab connection. No additional configuration is required.

## Related

- [Integrate a remote source code repository](/docs/cmp/configure/integrations/source-code-repository/): Linking a repository and setting credentials for your commits.
- [SSL root certificates](/docs/cmp/configure/access-and-security/security/ssl-root-certificates/): Trusting a self-signed certificate on GitHub Enterprise Server.