> 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/use-harness-platform/connectors/code-repositories/add-a-github-connector/git-hub-app-support.md). # Use a GitHub App in a GitHub connector Use a GitHub App to authenticate a GitHub connector, instead of a personal access token or OAuth. 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="" %} ## What you will learn from this topic * How to [create and register a GitHub App](#create-the-github-app) in your GitHub account or organization. * How to [install the GitHub App](#install-the-github-app) on the repositories you want Harness to access. * How to [generate a private key](#generate-a-private-key) for the app and store it as a Harness secret. * How to [configure a GitHub connector](#configure-the-github-connector) to use the GitHub App as its primary authentication method or its API access authentication method. *** ## Before you begin Before you begin working with GitHub apps, familiarize yourself with the following: * [Code repositories](/harness-platform/use-harness-platform/connectors/code-repositories/code-repositories-connectors-overview.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). You must also meet one or more of the following permission criteria before you create or install a GitHub App: * 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 and configure a GitHub App Perform the following steps to create, install, and configure a GitHub App for your GitHub connector. ### 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 does not 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-platform/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 did **not** 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 ``` ![GitHub App installation page showing the installation ID in the URL](https://173309742-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3F2TpHXhur2QtQnORSM9%2Fuploads%2Fgit-blob-df0e34d5377de00266b7c6b45949339264698307%2Fgit-hub-app-support-54.png?alt=media) 2. Get the **App ID** from the app's **General** tab. ![GitHub App General tab showing the App ID](https://173309742-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3F2TpHXhur2QtQnORSM9%2Fuploads%2Fgit-blob-db579190bd5c9476bf289dc51087f35aef1a356c%2Fgit-hub-app-support-55.png?alt=media) ### 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: ```bash 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-platform/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-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/git-hub-connector-settings-reference.md#authentication) or the [API access authentication method](/harness-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/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-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/git-hub-connector-settings-reference.md). The GitHub App is part of the **Credentials** settings. 4. For **Authentication**, select **GitHub App**. 5. Enter 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-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/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 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 %} ### Set up a PR trigger (optional) You can configure your pipelines to use [Git event triggers](/harness-platform/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-platform/use-harness-platform/triggers/triggers-reference.md#event-and-actions). *** ## Next steps * [Add a GitHub connector](/harness-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector.md): Configure a GitHub connector that uses this GitHub App for authentication or API access. * [GitHub connector settings reference](/harness-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/git-hub-connector-settings-reference.md): Review every setting available on the GitHub connector. * [Git event triggers](/harness-platform/use-harness-platform/triggers/triggering-pipelines.md): Run pipelines automatically in response to events in your GitHub repos. {% @harness-feedback/feedback module="harness-ai" pagePath="harness-ai/use-harness-platform/connectors/code-repositories/git-hub-app-support" %}