> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/troubleshooting-and-resources/knowledge-base/articles/backend-proxies/github-app-authentication.md).

# GitHub App authentication

Configure GitHub App authentication on an IDP Backend Proxy endpoint so plugins and Workflows call GitHub with an installation token

Use the `githubApp` authentication type on a Backend Proxy endpoint when you want Harness IDP to call the GitHub API with a GitHub App installation token. The proxy creates the token for you and injects it on every request, so plugins and Workflows do not need a personal access token in headers.

{% hint style="info" %}
IDP applies `auth.type: githubApp` only when the endpoint is called through `/v1/external-proxy/{endpoint}`.
{% endhint %}

![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-b81d0cfc76a20109a32090fb7c00085489bdad2a%2Fgithub-app-proxy-config.png?alt=media)

***

## Before you begin

Make sure you have the following in place:

* **Configure Backend Proxies plugin:** Enable **Configure Backend Proxies** plugin under **IDP** → **Configure** → **Plugins**. Go to [Plugins overview](https://developer.harness.io/internal-developer-portal/use-idp/plugins/overview.md) for plugin enablement.
* **GitHub App installed:** Create a GitHub App (or use an existing one), install it on the organization or account that owns the repositories you need, and note the App ID and installation ID.
* **Private key secret:** Store the GitHub App private key in a Harness secret. Plain-text private keys in the proxy YAML are not supported.

***

## Configure GitHub App authentication

To wire GitHub App authentication into a backend proxy endpoint, do the following:

1. Go to the YAML editor available in the **Configure Backend Proxies** plugin.
2. Click the **Edit YAML** button.
3. Add an endpoint and set `auth.type` to `githubApp`.

   <pre class="language-yaml" data-title="proxy.yaml" data-overflow="wrap"><code class="lang-yaml">proxy:
     endpoints:
       /githubAppProxy:
         target: https://api.github.com
         auth:
           type: githubApp
           appId: '&#x3C;APP_ID>'
           installationId: '&#x3C;INSTALLATION_ID>'
           privateKey: ${GITHUB_APP_PRIVATE_KEY}
   </code></pre>

   Map `GITHUB_APP_PRIVATE_KEY` to the Harness secret that holds the App private key in the plugin configuration variables, the same way you map other proxy secrets.
4. Scroll down and click **Save Configurations**.

***

## Configuration fields

Use the following fields under the endpoint `auth` block and `target`.

| Field                 | Required | Description                                                                                                 |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `target`              | Yes      | [Base URL](#target-url-formats) of the GitHub API. Must use HTTPS.                                          |
| `auth.type`           | Yes      | Must be set to `githubApp`.                                                                                 |
| `auth.appId`          | Yes      | GitHub App ID. Can be a literal string or a `${ENV_VAR}` reference backed by a Harness secret.              |
| `auth.installationId` | Yes      | GitHub App installation ID. Can be a literal string or a `${ENV_VAR}` reference backed by a Harness secret. |
| `auth.privateKey`     | Yes      | Must be a `${ENV_VAR}` reference backed by a Harness secret.                                                |

### Target URL formats

Set `target` to the GitHub API host, not the web UI host.

| GitHub product           | Target                      |
| ------------------------ | --------------------------- |
| GitHub.com               | `https://api.github.com`    |
| GitHub Enterprise Server | `https://<ghe-host>/api/v3` |

{% hint style="warning" %}
**Unsupported targets**

* Do not set `target` to `github.com`. Use `https://api.github.com` or the GitHub Enterprise `/api/v3` endpoint.
* Do not use HTTP. The target must use HTTPS.
  {% endhint %}

### Private key requirements

The proxy accepts the private key only through a Harness secret referenced as `${ENV_VAR}`.

| Secret type | Supported format               |
| ----------- | ------------------------------ |
| Secret Text | PEM private key                |
| Secret File | Base64-encoded PEM private key |

{% hint style="danger" %}
**Do not put the private key in YAML**

Plain-text private keys in the proxy configuration are not supported. Always [store the key in a Harness secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets) and reference it with `${ENV_VAR}`.
{% endhint %}

***

## Authentication behavior

When a request reaches an endpoint that uses `auth.type: githubApp` through the external proxy API (`/v1/external-proxy/{endpoint}`), the Backend Proxy does the following:

1. Generates a GitHub App installation token for the configured App ID and installation ID.
2. Sets the outgoing request header to `Authorization: Bearer ghs_*`.
3. Overrides any `Authorization` header that arrived on the incoming request.

{% hint style="info" %}
**Installation token, not App JWT**

The authentication type produces an installation token. It does not produce a GitHub App JWT. Endpoints that require a JWT, such as `/app` and `/app/installations`, are not supported through this auth type.
{% endhint %}

***

## Troubleshooting

<details>

<summary>401 Unauthorized</summary>

The target endpoint may require a GitHub App JWT. Installation-token auth cannot call JWT-only app endpoints such as `/app` and `/app/installations`.

</details>

<details>

<summary>403 Forbidden</summary>

The GitHub App installation may lack the permissions required for the API you called. Update the App permissions in GitHub, accept any permission updates on the installation, and retry.

</details>

<details>

<summary>404 Not Found</summary>

Confirm the path after your proxy endpoint maps to a real GitHub API resource, and confirm that the installation can access that organization, repository, or resource.

</details>

***

## Next steps

* [Architecture of IDP Plugins](https://developer.harness.io/internal-developer-portal/use-idp/plugins/delegate-proxy.md): How Backend Proxy and Delegate Proxy fit together.
* [GitHub Raw Files](https://developer.harness.io/internal-developer-portal/troubleshooting-and-resources/knowledge-base/articles/backend-proxies/github-raw.md): Call raw files from GitHub with a personal access token in proxy headers.
* [Custom Plugins V2](https://developer.harness.io/internal-developer-portal/use-idp/plugins/custom-plugins/custom-plugins-v2.md): Call a configured proxy endpoint from a custom plugin with `PluginAPI.proxyFetch()`.

{% @harness-feedback/feedback %}
