> 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.md).

# Add a GitHub connector

Add a GitHub connector so Harness pipelines can pull code and other files from your GitHub account or repositories.

GitHub is a cloud-based Git hosting platform used for source code management, collaboration, and open-source development. In addition to repository hosting, GitHub offers features such as pull requests, GitHub Actions, issue tracking, and GitHub Apps for fine-grained, repository-scoped authentication. Harness supports authenticating to GitHub using a personal access token, OAuth, or a GitHub App.

You connect Harness to GitHub using a Harness GitHub connector. The connector allows you to pull code and other files, such as Helm charts, Kubernetes manifests, and Terraform scripts, from your GitHub repositories for use in Harness pipelines.

Go to [Overview](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/code-repositories-connectors-overview.md) for information about all code repos connectors, such as scopes, permissions and connectivity modes.

## What you will learn from this topic

* How to [add a GitHub connector](#add-a-github-connector) to a Harness project so pipelines can pull code from GitHub.

***

## Before you begin

Before you create a GitHub connector, ensure you have:

* A GitHub account or organization, with at least one repository.
* A username and personal access token, an OAuth connection, an SSH key, or a GitHub App, with permission to read (and, if needed, write status checks to) the repositories you want to connect to.
* Permission to create connectors in Harness.

{% hint style="info" %}
**Harness recommends GitHub Apps**

Use a [GitHub App](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/git-hub-app-support.md) to authenticate your GitHub connector whenever possible. GitHub Apps offer more granular permissions than other authentication methods, and GitHub grants them [increased API 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).
{% endhint %}

***

## Add a GitHub connector

You can add a GitHub connector at the project, org, or account scope. This procedure covers the project scope, and the process is the same for org and account.

You can also add a GitHub connector directly when configuring a GitHub codebase or artifact source in a pipeline or service.

Follow the interactive guide below for a step-by-step walkthrough:

{% embed url="<https://app.arcade.software/share/pmJfnppijYaaujbHJrcr>" %}
Add a GitHub connector in Harness
{% endembed %}

Perform the following steps to add a GitHub connector:

1. Open your Harness project.
2. In **Project Settings**, select **Connectors**.
3. Click **New Connector**, then select **GitHub**. The GitHub Connector settings appear.

### Overview

Configure the identity fields for the connector.

In **Name**, enter a name for the connector. Optionally, add a description and tags. Click **Continue**.

### Details

Configure the following details:

1. For **URL Type**, select one of:
   * **Account**: Connect to an entire GitHub account or organization. The connector can be used for every repository in that account. Make sure the account has at least one repository, because you need a repository to test the connection.
   * **Repository**: Connect to a single GitHub repository.
2. For **Connection Type**, select **HTTP** or **SSH**.
3. Enter the **GitHub Account URL** or **GitHub Repository URL**, depending on the URL Type you selected. For example:
   * Account URL (HTTP): `https://github.com/YOUR_ACCOUNT_NAME/`
   * Repository URL (HTTP): `https://github.com/YOUR_ACCOUNT_NAME/YOUR_REPO_NAME.git`
   * Repository URL (SSH): `git@github.com:YOUR_ACCOUNT_NAME/YOUR_REPO_NAME.git`

{% hint style="info" %}
**GitHub Enterprise URLs**

For GitHub Enterprise, the URL must include your hostname and organization name, such as `https://mygithub.com/harness/repo-name.git` or `git@mygithub.com:harness/repo-name.git`.
{% endhint %}

4. If you selected **Account** for URL Type, enter a **Test Repository**. Harness uses this repository only to validate the connection. You specify the actual repository to use when you reference the connector in a pipeline.
5. Click **Continue**.

### Credentials

Configure the credentials based on the connection type you selected. For **Authentication**, select one of the following methods. HTTP connections support **Username and Token**, **OAuth**, **GitHub App**, or **Anonymous**. SSH connections require **SSH Key**.

* **Username and Token**:
  * **Username**: Enter your GitHub account username. You can use plaintext or a [Harness encrypted text secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md).
  * **Personal Access Token**: Select or create a new [Harness encrypted text secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md) to store your GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). The token must have all `repo`, `user`, and `admin:repo_hook` scopes.
* **OAuth**: Click **Link to GitHub**, then authorize access to your GitHub organization or account in the browser tab that opens.
* **GitHub App**:
  * **GitHub Installation Id**: Enter the GitHub installation Id from your installed GitHub App.
  * **GitHub Application Id**: Enter the GitHub application Id from your installed app.
  * **GitHub Private Key**: Select or create a new [Harness encrypted file secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-file-secrets.md) that stores the app's PEM private key. Go to [Use a GitHub App in a GitHub connector](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/git-hub-app-support.md) to create and install the app before you configure the connector.
* **Anonymous**: No credentials are required.
* **SSH Key**: Select or create a new [Harness SSH credential secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-ssh-secrets.md) to store your SSH key, or a GitHub [deploy key](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys) scoped to a single repository. The SSH credential's **Username** must be `git`, and the key must be in PEM format using ECDSA or Ed25519.

{% hint style="info" %}
**Enable API access for build status updates and triggers**

If you want to use Git Experience, send build or PR status updates back to GitHub, or to support Git event triggers and webhooks using the connector, select **Enable API access** and provide a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) as a [Harness encrypted text secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md).
{% endhint %}

### Select Connectivity Mode

Select how Harness connects with GitHub:

* **Connect through Harness Platform**: Use a direct, secure communication between Harness and GitHub. All credentials are encrypted and stored in the Secret Manager configured in Harness. This connectivity mode is required for [Harness Cloud build infrastructure](https://developer.harness.io/docs/continuous-integration/use-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure/).
* **Connect through a Harness Delegate**: Harness communicates with GitHub through a Harness Delegate you install in your environment, behind your corporate firewall.

### Delegates Setup

If you selected **Connect through a Harness Delegate**, select either:

* **Use any available Delegate**: Harness selects an available delegate at runtime.
* **Only use Delegates with all of the following tags**: Select specific delegates for Harness to use with this connector.

Click **Save and Continue**.

### Test Connection

Click **Finish** after the connection test succeeds. The connector is listed in **Connectors**.

If the connection test fails:

* Confirm the account or repository URL matches the format for your selected URL Type and Connection Type.
* Confirm the credential secret, OAuth link, or GitHub App has not expired and has the required repository permissions.
* If you are connecting through a delegate, confirm the delegate can reach GitHub over the network.

{% hint style="info" %}
**Kubernetes delegate with self-signed certificates**

If this connector allows API access and connects through a Harness Delegate that uses self-signed certificates, you must specify `ADDITIONAL_CERTS_PATH` in the delegate pod. Go to [Configure a Kubernetes build farm to use self-signed certificates](https://developer.harness.io/docs/continuous-integration/use-ci/set-up-build-infrastructure/k8s-build-infrastructure/configure-a-kubernetes-build-farm-to-use-self-signed-certificates) for details.
{% endhint %}

***

## Sample YAML

The following example shows a YAML for the GitHub connector created in this guide.

<details>

<summary>YAML - GitHub connector</summary>

```yaml
connector:
  name: your-github-connector # Replace with a name for your connector
  identifier: yourgithubconnector # Replace with a unique identifier
  description: ""
  accountIdentifier: your-account-identifier # Replace with your Harness account identifier
  type: Github
  spec:
    url: yourgithubrepourl # Replace with your GitHub account or repository URL
    authentication:
      type: Http # Use "Ssh" instead if you selected SSH as the Connection Type
      spec:
        type: UsernameToken
        spec:
          username: youraccountusername # Replace with your GitHub username, or a Harness expression referencing a secret
          tokenRef: yourpersonalaccesstoken # Replace with a reference to the Harness secret storing your personal access token
    apiAccess:
      type: Token
      spec:
        tokenRef: yourpersonalaccesstoken # Replace with a reference to the Harness secret storing the token used for Enable API access
    executeOnDelegate: true # Set to false if you selected Connect through Harness Platform
    ignoreTestConnection: false # Set to true only to skip connector preflight checks
    type: Repo # Use "Account" instead if you selected Account as the URL Type
```

</details>

For the full connector YAML schema, including how to skip connector preflight checks, go to [Create a connector using YAML](https://developer.harness.io/harness-platform/use-harness-platform/connectors/create-a-connector-using-yaml.md).

***

## Next steps

* [Use a GitHub App in a GitHub connector](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/git-hub-app-support.md): authenticate the connector with more granular permissions and higher rate limits.
* [Use delegate selectors](https://developer.harness.io/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md): control which delegates can connect to this connector.
* [Add a secret manager](https://developer.harness.io/harness-platform/use-harness-platform/secrets/secrets-management.md): store connector credentials in a secret manager instead of the Harness built-in secret manager.
