> 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/harness-platform/3.0/harness-platform-resources/connectors/code-repositories/git-hub-app-support.md). # Use a GitHub App in a GitHub connector You can use a GitHub App to provide authentication for a GitHub connector. This enables API access to GitHub through the GitHub App. Harness recommends using GitHub Apps for GitHub connectors, because GitHub Apps offer more granular permissions than other authentication methods and [increased rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-github-app-installations). The following video uses Harness Continuous Delivery to demonstrate the benefits, features, and configuration of GitHub Apps in Harness. {% embed url="" %} This topic assumes you have an understanding of: * [Connecting to code repos with Harness](/harness-ai/use-harness-platform/connectors/code-repositories/connect-to-code-repo.md). * [Creating GitHub Apps](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps). * [Installing GitHub Apps](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app). ### Permissions requirements You must meet one or more of the following criteria: * You can install GitHub Apps on your personal account or under an organization where you have administrative access. * You have admin permissions on a GitHub repo under a GitHub organization, and you can install GitHub Apps in that repo. * You will install the GitHub App in a repo that requires an organization's permission, and the organization owner has approved the application, and can provide approvals as needed to proceed with app installation. ### Create the GitHub App You can create and register GitHub Apps in your personal GitHub account or in any GitHub organization where you have administrative access. Follow the instructions in the GitHub documentation on [Creating a GitHub App](https://docs.github.com/en/developers/apps/creating-a-github-app). Populate the settings as follows: * **GitHub App Name:** Enter a name. * **Homepage URL:** Enter `https://harness.io/`. * **Webhook:** Deselect **Active**. The app is used for authentication and doesn't need to receive webhook events. * **Permissions:** Configure the following **Repository Permissions**. * **Commit statuses**: Select **Read & write**. * **Contents:** Select **Read & write**. * **Metadata:** Select **Read-only**. * **Pull requests**: Select **Read & write**. This is required for the **Issue Comment** [event trigger](/harness-ai/use-harness-platform/triggers/triggers-reference.md#event-and-actions) for Github. * **Webhooks:** Select **Read & write**. * **Where can this GitHub App be installed:** Select **Any account**. The app must be public to use it with a GitHub connector. {% hint style="info" %} **PRIVATE APPS** A private app can only be installed on the account that owns the app. Your app is private if you *didn't* select **Any account** for **Where can this GitHub App be installed**. You must edit your app and make it public. For instructions, go to the GitHub documentation on [Changing the visibility of a GitHub App](https://docs.github.com/en/apps/maintaining-github-apps/modifying-a-github-app-registration#changing-the-visibility-of-a-github-app). {% endhint %} ### Install the GitHub App Follow the instructions in the GitHub documentation on [Installing your own GitHub App](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app), and note the following: * For **Repository access**, select **Only select repositories**, and then select the repos you want to connect with through your Harness GitHub connector. * Configure these **Permissions**: * **Metadata: Read** * **Code: Read & write** * **Commit statuses: Read & write** * **Pull Requests: Read & write** ### Get the Installation ID and App ID You need the **Installation ID** and **App ID** to configure your Harness GitHub connector. 1. Get the **Installation ID** from the URL of the installed app, such as: ``` https://github.com/settings/installations/INSTALLATION_ID ``` 2. Get the **App ID** from the app's **General** tab. ### Generate a private key You need a private key for your GitHub app to configure your Harness GitHub connector. 1. Follow the instructions in the GitHub documentation for [generating private keys for GitHub Apps](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys) 2. Save the private key file to your local machine. GitHub only stores the public portion of the key. 3. Open a terminal and `cd` to the folder containing the key. 4. Run the following command to convert the key file to the necessary format for the Harness GitHub connector. Replace `YOUR_KEY.pem` with the name of the PEM file you saved: ``` openssl pkcs8 -topk8 -inform PEM -outform PEM -in .pem -out converted-github-app.pem -nocrypt ``` 5. In Harness, store the converted key file as a [Harness encrypted file secret](/harness-ai/use-harness-platform/secrets/add-file-secrets.md). ### Configure the GitHub connector You can use your GitHub App as either the [primary authentication method](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-hub-connector-settings-reference.md#authentication) or the [API access authentication method](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-hub-connector-settings-reference.md#enable-api-access) for your GitHub connector. {% tabs %} {% tab title="Primary authentication" %} 1. In your Harness project, select **Connectors** under **Project Setup**. 2. Create a new connector or edit an existing GitHub connector. 3. Configure the [GitHub connector settings](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-hub-connector-settings-reference.md). The GitHub App is part of the **Credentials** settings. 4. For **Authentication**, select **GitHub App**. 5. Enter the your GitHub [installation ID and app ID](#get-the-installation-id-and-app-id). 6. Select your [private key file secret](#generate-a-private-key). 7. Select **Continue**. 8. If the connection test succeeds, select **Finish** to save the connector. {% endtab %} {% tab title="API access authentication" %} 1. In your Harness project, select **Connectors** under **Project Setup**. 2. Create a new connector or edit an existing GitHub connector. 3. Configure the [GitHub connector settings](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-hub-connector-settings-reference.md). The GitHub App is part of the **Credentials** settings. 4. Select **Enable API access**. This setting is only available for connection types and authentication methods where it is not already enabled by default. 5. For **API Authentication**, select **GitHub App**. 6. Enter the your GitHub [installation ID and app ID](#get-the-installation-id-and-app-id). 7. Select your [private key file secret](#generate-a-private-key). 8. Select **Continue**. 9. If the connection test succeeds, select **Finish** to save the connector. {% endtab %} {% endtabs %} ### Option: Set up a PR trigger You can configure your pipelines to use [Git event triggers](/harness-ai/use-harness-platform/triggers/triggering-pipelines.md) so that builds automatically run in response to events in your Git repos. If you want to set up a PR trigger, make sure the webhook definition uses the **Pull Request** [event](/harness-ai/use-harness-platform/triggers/triggers-reference.md#event-and-actions).