Skip to main content

GitHub Connector Settings Reference

This topic provides settings and permissions for the GitHub Connector.

You can also use a GitHub App for authentication in a Harness GitHub Connector. See Use a GitHub App in a GitHub Connector.

Name​

The unique name for this Connector.

ID​

See Entity Identifier Reference.

Description​

Text string.

Tags​

See Tags Reference.

URL Type​

You can select Git Account (which is a GitHub organization) or Git Repository.

You can add a connection to your entire Git org or just a repo in the org. Selecting a Git org enables you to use one Connector for all of your subordinate repos.

Later, when you test this connection, you'll use a repo in the org.

In either case, when you use the Connector later in Harness, you'll specify which repo to use.

Connection Type​

You can select HTTPS or SSH for the connection.

You will need to provide the protocol-relevant URL in URL.

If you use Two-Factor Authentication for your Git repo, you connect over HTTPS or SSH. HTTPS connections require a personal access token.

For SSH, make sure that the key is PEM and not OpenSSH. To generate an SSHv2 key, use: 
ssh-keygen -t rsa -m PEM 
Use rsa and -m PEM to make sure that the algorithm and the key are PEM.
Next, follow the prompts to create the PEM key. See the  ssh-keygen man page and Connecting to GitHub with SSH.Starting March 15, 2022, GitHub is fully deprecating RSA with SHA-1. GitHub will allow ECDSA and Ed25519 to be used. RSA keys uploaded after this date will work with SHA-2 signatures only (RSA keys uploaded before this date will continue to work with SHA-1). See Improving Git protocol security on GitHub from GitHub.

Generating an SSH key in ECDSA looks like this:

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

GitHub Repository URL​

The URL for a Git org or repo. The URL format must match the Connection Type you selected --for example:

  • HTTPS: https://github.com/wings-software/harness-docs.git.
  • SSH: [email protected]:wings-software/harness-docs.git.

You can get the URL from GitHub using its Code feature:

If you selected Git Repository in URL Type, enter the full URL for the repo with the format https://github.com/[org-name]/[repo-name].

If you selected Git Account in URL Type, enter the URL without the repo name, like https://github.com/[org-name]. You will need to provide a repo name before you can use the Connector in Harness.

Authentication​

Read-only GitHub repos also require a username and password/token.You can use a password/token for HTTPS credentials.

If you selected SSH as the connection protocol, you must add the SSH Key to use with the connection. 

Username​

Your personal GitHub account username.

Personal Access Token​

A Harness Encrypted Text secret for the credentials of your GitHub user account.

A Personal Access Token (PAT) is required if your GitHub authentication uses 2FA.

Typically, 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>

If you have Two-Factor Authentication set up in your Git repo, then you need to generate a personal access token in your repo and enter that token in the Personal Access Token field. In GitHub, you can set up the personal access token at https://github.com/settings/tokens/new.

PAT Permissions​

To use a personal access token with a GitHub organization that uses SAML single sign-on (SSO), you must first authorize the token. See Authorizing a personal access token for use with SAML single sign-on from GitHub.* The GitHub user account used to create the Personal Access Token must have admin permissions on the repo.

  • GitHub doesn't provide a way of scoping a PAT for read-only access to repos. You must select the following permissions:

SSH Key​

If you selected SSH as the connection protocol, you must add the SSH Key to use with the connection as a Harness Encrypted Text secret. For detailed steps to create an SSH Key, see Add new SSH Key.

Harness also supports GitHub 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 selected in URL Type.

Enable API access​

This option is required for using Git-based triggers, Webhooks management, and updating Git statuses.

You can use the same token you used in Personal Access Token.

API Authentication​

You should use the same Personal Access Token for both Authentication and API Authentication.