> 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/ref-source-repo-provider/git-hub-connector-settings-reference.md).

# GitHub connector settings reference

This topic provides settings and permissions for the GitHub connector. For instructions and more information about code repo connectors, go to [Connect to a Git repository](/harness-ai/use-harness-platform/connectors/code-repositories/connect-to-code-repo.md).

### Overview settings <a href="#overview-settings" id="overview-settings"></a>

* **Name:** The unique name for this connector. Harness generates an **Id** ([Entity Identifier](/harness-ai/use-harness-platform/references/entity-identifier-reference.md)) based on the **Name**. You can edit the **Id** during initial connector creation. Once you save the connector, the **Id** is locked.
* **Description:** Optional text string.
* **Tags:** Optional labels you can use for filtering. For details, go to the [Tags reference](/harness-platform/3.0/harness-platform-resources/tags/overview.md#create-tags-for-pipelines).

### Details settings <a href="#details-settings" id="details-settings"></a>

The **Details** settings specify which GitHub account or repository you want this connector to connect to, whether to connect over HTTP or SSH, and the URL to use.

#### URL Type <a href="#url-type" id="url-type"></a>

Select **Account** to connect an entire GitHub account (or organization). This option lets you use one connector to connect to all repositories in the specified GitHub account. Make sure you have at least one repo in the account; you need a repo to test the connection and save the connector.

Select **Repository** to connect to a single, specific GitHub repository.

#### Connection Type <a href="#connection-type" id="connection-type"></a>

Select the protocol, **HTTP** or **SSH**, to use for cloning and authentication. The **Connection Type** determines the URL format required for the **GitHub Account/Repository URL** field. It also determines the **Authentication** method you must use in the [Credentials settings](#credentials-settings).

#### GitHub Account/Repository URL <a href="#github-accountrepository-url" id="github-accountrepository-url"></a>

Enter the URL for the GitHub account or repository that you want to connect to. The required value is determined by the **URL Type** and **Connection Type**.

{% tabs %}
{% tab title="URL Type: Account" %}
In the **GitHub Account URL** field, provide only the account-identifying portion of the GitHub URL, such as `https://github.com/YOUR_ACCOUNT_NAME/`. Do not include a repo name. The URL format depends on the **Connection Type**:

* **HTTP:** `https://github.com/YOUR_ACCOUNT_NAME/` or `https://github.com`
* **SSH:** `git@github.com:YOUR_ACCOUNT_NAME/`

#### Test Repository <a href="#test-repository" id="test-repository"></a>

This field is only required if the **URL Type** is **Account**. Provide the name of a repo in your GitHub account that Harness can use to test the connector. Harness uses this repo to validate the connection only. When you use this connector in a pipeline, you'll specify a true code repo in your pipeline configuration or at runtime.
{% endtab %}

{% tab title="URL Type: Repository" %}
In the **GitHub Repository URL** field, provide the complete URL to the GitHub repository that you want this connector to point to. The URL format depends on the **Connection Type**:

* **HTTP:** `https://github.com/YOUR_ACCOUNT_NAME/YOUR_REPO_NAME.git`
* **SSH:** `git@github.com:YOUR_ACCOUNT_NAME/YOUR_REPO_NAME.git`
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
**GITHUB ENTERPRISE URLS**

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

### Credentials settings <a href="#credentials-settings" id="credentials-settings"></a>

Provide authentication credentials for the connector.

#### Authentication <a href="#authentication" id="authentication"></a>

Authentication is required for all accounts and repos, including read-only repos. The **Connection Type** you chose in the [Details settings](#details-settings) determines the available **Authentication** methods:

* For **HTTP** connections, you can use **Username and Token**, **OAuth**, or **GitHub App** authentication.
* For **SSH** connections, you must use **SSH Key** authentication.

{% hint style="info" %}
Whenever possible, Harness recommends [using GitHub Apps with GitHub connectors](/harness-ai/use-harness-platform/connectors/code-repositories/git-hub-app-support.md) for [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).
{% endhint %}

{% tabs %}
{% tab title="Username and Token" %}

1. For **Authentication**, select **Username and Token**.
2. In the **Username** field, enter your personal GitHub account name. You can use either plaintext or a [Harness encrypted text secret](/harness-ai/use-harness-platform/secrets/add-use-text-secrets.md).
3. In the **Personal Access Token** field, provide a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) as a [Harness encrypted text secret](/harness-ai/use-harness-platform/secrets/add-use-text-secrets.md).

{% hint style="info" %}
**PERSONAL ACCESS TOKEN PERMISSIONS**

* The GitHub user account that you use to create the token must have admin permissions on the repo.
* For GitHub organizations that use SAML single sign-on (SSO), you must [authorize the token for use with SAML single sign-on](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on).
* The token must have all `repo`, `user`, and `admin:repo_hook` scopes. GitHub doesn't provide a way to scope tokens for read-only access to repos.
  {% endhint %}

{% hint style="info" %}
You can validate your token from the command line before using it in Harness. For example:

`curl -i https://api.github.com -u <username>:<token>`
{% endhint %}
{% endtab %}

{% tab title="OAuth" %}
{% hint style="info" %}
Currently, OAuth for GitHub connectors is behind a feature flag. Contact [Harness Support](mailto:support@harness.io) to enable the feature.
{% endhint %}

1. For **Authentication**, select **OAuth**.
2. Select **Link to GitHub** to open a new browser tab and authorize access to your GitHub organization/account.
   {% endtab %}

{% tab title="SSH Key" %}
SSH connections require an SSH key or a GitHub deploy key.

[GitHub deploy keys](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys) grant access to a single repo. Using a deploy key ensures that the connector only works with the specific repo you defined in the [Details settings](#details-settings).

SSH keys must be in PEM format. OpenSSH keys are not supported. For details on creating SSH keys and adding them to your GitHub account, go to the GitHub documentation about [adding a new SSH Key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). In Harness, SSH Keys are stored as [Harness SSH credential secrets](/harness-ai/use-harness-platform/secrets/add-use-ssh-secrets.md). When creating an SSH credential secret for a code repo connector, the SSH credential's **Username** must be `git`. Always save the ssh key as a file secret.

{% hint style="info" %}
If you use the `keygen` command to generate an SSH key, include arguments such as `rsa` and `-m PEM` to ensure your key is properly formatted and uses the RSA algorithm. For example, this command creates an SSHv2 key:

```
ssh-keygen -t rsa -m PEM
```

Make sure to follow the prompts to finish creating the key. For more information, go to the Linux [ssh-keygen man page](https://linux.die.net/man/1/ssh-keygen).

For GitHub repos, your SSH key must use ECDSA or Ed25519 instead of RSA. As an example, the following `ssh-keygen` command generates a PEM-formatted SSH key in ECDSA:

```
ssh-keygen -t ecdsa -b 256 -f /home/user/Documents/ECDSA/key -m pem
```

For more information about GitHub's deprecation of RSA support, go to the GitHub announcement on [Improving Git protocol security on GitHub](https://github.blog/2021-09-01-improving-git-protocol-security-github/#when-are-these-changes-effective).
{% endhint %}
{% endtab %}

{% tab title="GitHub App (Recommended)" %}
You can use a GitHub App to authenticate a Harness GitHub connector. To use this authentication method, you need to create and install a GitHub App, get the app's **installation ID** and **app ID**, and create a private key for the app. For instructions, go to [Use a GitHub App in a GitHub connector](/harness-ai/use-harness-platform/connectors/code-repositories/git-hub-app-support.md).

{% hint style="info" %}
Harness recommends [using GitHub Apps with GitHub connectors](/harness-ai/use-harness-platform/connectors/code-repositories/git-hub-app-support.md) for [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).
{% endhint %}

1. For **Authentication**, select **GitHub App**.
2. Enter the **GitHub Installation Id**. You can find the installation ID in the URL of your installed GitHub App, such as:

   ```
   https://github.com/settings/installations/INSTALLATION_ID
   ```
3. Enter the **GitHub Application Id**. You can find the app ID on the **General** tab when viewing your GitHub App in GitHub.
4. For **GitHub Private Key**, provide your GitHub App's PEM key file as a [Harness encrypted file secret](/harness-ai/use-harness-platform/secrets/add-file-secrets.md).
   {% endtab %}
   {% endtabs %}

#### Enable API access <a href="#enable-api-access" id="enable-api-access"></a>

This setting is only available for connection types and authentication methods where it is not already enabled by default.

API access is required for any operations that require Harness to call GitHub APIs, such as using the Harness Git Experience, cloning codebases from PRs, automatically detecting branch names when you manually run pipelines, using Git webhook triggers, and updating Git statuses.

Enabling API access requires configuring an API authentication method, either a personal access token or a GitHub App.

{% tabs %}
{% tab title="Personal Access Token" %}

1. For **API Authentication**, select **Personal Access Token**.
2. In the **Personal Access Token** field, provide a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) as a [Harness encrypted text secret](/harness-ai/use-harness-platform/secrets/add-use-text-secrets.md).

   With **Username and Token** authentication, use the same personal access token secret for both **Personal Access Token** fields.

<details>

<summary>Personal access token permissions</summary>

* The GitHub user account that you use to create the token must have admin permissions on the repo.
* For GitHub organizations that use SAML single sign-on (SSO), you must [authorize the token for use with SAML single sign-on](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on).
* The token must have all `repo`, `user`, and `admin:repo_hook` scopes. GitHub doesn't provide a way to scope tokens for read-only access to repos.

</details>
{% endtab %}

{% tab title="GitHub App" %}
To use this authentication method, you need to create and install a GitHub App, get the app's **installation ID** and **app ID**, and create a private key for the app. For instructions, go to [Use a GitHub App in a GitHub connector](/harness-ai/use-harness-platform/connectors/code-repositories/git-hub-app-support.md).

1. For **API Authentication**, select **GitHub App**.
2. Enter the **GitHub Installation Id**. You can find the installation ID in the URL of your installed GitHub App, such as:

   ```
   https://github.com/settings/installations/INSTALLATION_ID
   ```
3. Enter the **GitHub Application Id**. You can find the app ID on the **General** tab when viewing your GitHub App in GitHub.
4. For **GitHub Private Key**, provide your GitHub App's PEM key file as a [Harness encrypted file secret](/harness-ai/use-harness-platform/secrets/add-file-secrets.md).

{% hint style="info" %}
Ensure your private key is in the correct format. For detailed steps, refer to [Generate a private key](/harness-ai/use-harness-platform/connectors/code-repositories/git-hub-app-support.md#generate-a-private-key).

Using an incorrect format will result in errors such as: **Invalid request: Failed to generate token**
{% endhint %}
{% endtab %}
{% endtabs %}

### Connectivity Mode settings <a href="#connectivity-mode-settings" id="connectivity-mode-settings"></a>

Select whether you want Harness to connect directly to your GitHub account or repo, or if you want Harness to communicate with your GitHub account or repo through a delegate. If you plan to use this connector with [Harness Cloud build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md), you must select **Connect through Harness Platform**.

<details>

<summary>About connectivity modes</summary>

If you select **Connect through the Harness Platform**, the Harness Manager exchanges a key pair with the Secrets Manager configured in Harness using an encrypted connection. Next, the Harness Manager uses the encrypted key and the encrypted secret and then discards them. The keys never leave the Harness Manager. Secrets are always encrypted in transit, in memory, and in the Harness database.

**Connect through a Harness Delegate**, a [Harness Delegate](/harness-platform/3.0/harness-platform-resources/delegates/delegate-closed-beta/delegate-overview.md) handles the connection. This option is often used for [Harness Self-Managed Enterprise Edition Overview](/self-managed-enterprise-edition/new-to-self-managed-enterprise-edition/smp-overview.md).

</details>

{% hint style="info" %}
For private network connectivity options with Harness Cloud, see [Private network connectivity options](/harness-platform/3.0/harness-platform-resources/references/private-network-connectivity/private-network-connectivity.md).
{% endhint %}

#### Delegates Setup <a href="#delegates-setup" id="delegates-setup"></a>

If you select **Connect through a Harness Delegate**, you can select **Use any available Delegate** or **Only use Delegates with all of the following tags**.

If you want to use specific delegates, you must identify those delegates. For more information, go to [Use delegate selectors](/harness-ai/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md).

#### Kubernetes delegate with self-signed certificates <a href="#kubernetes-delegate-with-self-signed-certificates" id="kubernetes-delegate-with-self-signed-certificates"></a>

If your codebase 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, as described in [Configure a Kubernetes build farm to use self-signed certificates](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/configure-a-kubernetes-build-farm-to-use-self-signed-certificates.md#enable-self-signed-certificates).

***

### Important notes <a href="#important-notes" id="important-notes"></a>

#### Branch listing and search <a href="#branch-listing-and-search" id="branch-listing-and-search"></a>

When selecting branches in the Harness UI (for example, when configuring a pipeline to use a specific branch), you can search for branches and load additional results:

* **Prefix-based search**: As you type in the branch selection field, Harness searches for branches that match your search term as a prefix. This uses the v2 list branches API to find branches beyond the initially loaded set.
* **Load more**: If your repository has more than 100 branches, you can scroll down in the branch selection dropdown to load additional pages of branches. This infinite scroll capability ensures that all branches in your repository are eventually available for selection.

These improvements are available with go-scm library version 1.42.9 or later and Harness Delegate version 26.06.89500 or later.

#### File size limitation <a href="#file-size-limitation" id="file-size-limitation"></a>

The GitHub Contents API, which Harness uses to fetch files from repositories, has a 1 MB file size limit. If you attempt to fetch a file larger than 1 MB (such as a large Kubernetes manifest or Custom Resource Definition), the operation will fail.

**Workaround:** Use the platform-agnostic Git connector instead of the GitHub connector. The Git connector uses git clone to fetch files, which does not have the same file size limitation. Go to [Use the platform-agnostic Git connector](/harness-ai/use-harness-platform/connectors/code-repositories/connect-to-code-repo.md#use-the-platform-agnostic-git-connector) to connect to your code repository without the file size constraint.

Go to the [GitHub REST API documentation on repository contents](https://docs.github.com/en/rest/repos/contents#get-repository-content) to understand the file size constraints imposed by the GitHub Contents API.