GitHub App authentication

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.

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.
2. Under Repository permissions, set Contents to Read-only for refresh, or Read and write if CMP pushes to the repository.
3. Generate a private key on the App’s settings page and download the .pem file.
4. Install the App on the organization, or on the specific repositories that CMP accesses.
5. Note the App ID from the App’s settings page, under General > App ID. This is a number, not the Client ID.

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.
2. Select the GitHub App Credentials tab, then select New GitHub App Credential.
3. Provide a Name to identify the credential when selecting it on a connection.
4. Provide the numeric App ID.
5. Paste the full contents of the .pem file into Private Key (PEM), including the -----BEGIN and -----END lines.
6. Optionally provide an API Base URL Override. Leave this blank unless your GitHub Enterprise Server instance uses a non-standard API base.
7. 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.
2. Set Authentication Method to GitHub App. The Username and Password or Token fields are replaced by the credential selector.
3. Select a GitHub App Credential.
4. 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.

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. 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/:

{
  "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.

Troubleshooting

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.