GitHub OAuth app integration overview

Cloud

GitHub authorization with CircleCI is changing. Starting August 2023 when you authorize your CircleCI account with GitHub, you may find this will be done through our GitHub App, rather than the GitHub OAuth app. You can see which account type you have by heading to the CircleCI web app, select Dashboard from the sidebar, and inspect the URL in your browser:

This style of URL indicates you authenticated with the GitHub App: https://app.circleci.com/organization/circleci/UTxCZDiJ9MLGLC8hR1ZDmg
This style of URL indicates you authenticated with the GitHub OAuth app: https://app.circleci.com/pipelines/github/<your GitHub username/organization name>

For more information about the differences, see the GitHub docs comparison page.

If your CircleCI organization is authenticated with GitHub through the GitHub OAuth app, the content on this page is for you.

Introduction

When you add a project to CircleCI, the following settings are added to the repository using the permissions you gave CircleCI when you signed up:

A deploy key that is used to check out your project from GitHub.
A service hook (or "push hook") that is used to notify CircleCI when you push to GitHub.

CircleCI builds push hooks by default. Builds are triggered for all push hooks for the repository and PUSH is the most common case of triggering a build.

Some additional, less common cases where CircleCI uses hooks are as follows:

CircleCI processes PR hooks (pull request hooks) to store PR information for the CircleCI app. If the Only build pull requests setting is enabled within CircleCI, CircleCI will only trigger builds when a PR is opened, or when there is a push to a branch for which there is an existing PR. Even if this setting is enabled, CircleCI will always build all pushes to the project’s default branch.
If the Build forked pull requests setting is enabled in CircleCI, CircleCI will trigger builds in response to PRs created from forked repositories.

These settings can be found in each project’s individual Project Settings section of the CircleCI web app.

The ability to override the Only build pull requests setting is supported. Specifically, CircleCI will run validation on all commits from additional, non-default branches that are specified via regular expression (for example, release.\*). Details on how to enable can be found on our community forum.

It is possible to edit the webhooks in GitHub to restrict events that trigger a build. Editing the webhook settings lets you change which hooks get sent to CircleCI, but does not change the types of hooks that trigger builds. CircleCI will always build push hooks, and build on PR hooks (depending on settings), but if you remove push hooks from the webhook settings, CircleCI will not build.

Refer to the GitHub Edit a Hook document for details.

Refer to the CircleCI documentation on Workflow filters for information on how to build tag pushes.

Permissions overview

CircleCI requests the following permissions from GitHub, defined in the GitHub permissions model.

Read Permission

Get a user’s email address

Write Permissions

Get a list of a user’s repositories
Add an SSH key to a user’s account

Admin Permissions, needed for setting up a project

Add deploy keys to a repository
Add service hooks to a repository

CircleCI only asks for permissions that are absolutely necessary. However, as a GitHub OAuth app, CircleCI is constrained by the specific permissions available via GitHub’s OAuth scopes. For example, getting a full list of a user’s repository, public and private, from GitHub, requires the repo scope, which is write-level access. GitHub does not provide a read-only OAuth scope for listing all of a user’s repositories.

SAML SSO

Enabling SAML protection on a GitHub org can cause changes to CircleCI’s settings related to GitHub Checks and GitHub status updates. Ensure these settings are configured for their desired state after enabling SAML for your organization. You can find these settings at:

GitHub Checks, from the GitHub website, select Organization Settings VCS GitHub Checks
GitHub status updates, from the CircleCI web app Project Settings Advanced GitHub Status Updates

For more information on GitHub Checks and GitHub status updates, see the Enabling GitHub checks.

Connect a GitHub account

In the CircleCI web app, select the organization you want to connect to GitHub and navigate to the User Settings by clicking on the user icon on the bottom of sidebar. Here you will be able to select GitHub. Once connected, you should see any existing projects populate on your dashboard, and you can choose which projects to follow.

Next you will need to set up the necessary permissions to run your projects on CircleCI.

Disconnect a GitHub account

Follow these steps to disconnect your CircleCI account from GitHub.

When disconnecting a VCS connection using the method described here, any existing personal API keys will be invalidated. Any SSH keys, or deploy keys may also be invalidated. Disconnecting the VCS connection is intended to be used when issues arise, for example:

You joined the wrong organization
You connected with the wrong GitHub user account
Changes to the organization name in your VCS

From the CircleCI web app, select the organization you want to disconnect from GitHub. To do this use the org switcher at the top of the sidebar
Navigate to User Settings by clicking on the user icon on the bottom of sidebar, then select Account Integrations
You will see a list of connections along with the GitHub organizations they are associated with. Select Disconnect for the GitHub connection you wish to disconnect.

Once disconnected, you will be redirected to the CircleCI login page. To reconnect your account, log in to CircleCI, navigate to user settings (icon at the bottom of the web app sidebar), and under Account Integrations select Connect next to GitHub.

Deploy keys and user keys

What is a deploy key?

When you add a new project, CircleCI creates a deployment key on GitHub for your project. A deploy key is an SSH key-pair, one public, one private. GitHub stores the public key, and CircleCI stores the private key. The deployment key gives CircleCI access to a single repository. To prevent CircleCI from pushing to your repository, this deployment key is read-only.

If you want to push to the repository from your builds, you will need a deployment key with write access. See the below section for GitHub-specific instructions to create a deployment key.

What is a user key?

A user key is user-specific an SSH key-pair. GitHub stores the public key, and CircleCI stores the private key. Possession of the private key gives the ability to act as that user, for purposes of 'git' access to projects.

What is the difference between deploy keys and user keys?

Deploy keys and user keys are the only key types that GitHub supports. Deploy keys are globally unique (for example, no mechanism exists to make a deploy key with access to multiple repositories) and user keys have no notion of scope separate from the user associated with them.

To achieve fine-grained access to more than one repository, consider creating what GitHub calls a machine user. Give this user exactly the permissions your build requires, and then associate its user key with your project on CircleCI.

Create additional GitHub SSH keys

If you need additional SSH keys to access other services, you can create additional keys by following the steps below.

In this example, the GitHub repository is https://github.com/you/test-repo, and the CircleCI project is https://app.circleci.com/pipelines/github/you/test-repo.

Create an SSH key-pair by following the GitHub instructions. When prompted to enter a passphrase, do not enter one (below is one example command to generate a key on macOS):
```
  ssh-keygen -t ed25519 -C "your_email@example.com"
```
Go to https://github.com/you/test-repo/settings/keys, and select Add Deploy Key. Enter a title in the "Title" field, then copy and paste the public key you created in step 1. Check Allow write access, then select Add key.
Go to your project settings in the CircleCI app, select SSH Keys, and Add SSH key. In the "hostname" field, enter github.com and add the private key you created in step 1. Then select Add SSH Key.

In your .circleci/config.yml file, add the fingerprint to a job using the add_ssh_keys key:

  version: 2.1

  jobs:
    deploy-job:
      steps:
        - add_ssh_keys:
            fingerprints:
              - "SO:ME:FIN:G:ER:PR:IN:T"

When you push to your GitHub repository from a job, CircleCI will use the SSH key you added.

How are private keys used?

When CircleCI builds your project, the private key is installed into the .ssh directory and SSH is subsequently configured to communicate with your version control provider. Therefore, the private key is used for:

Checking out the main project
Checking out any GitHub-hosted submodules
Checking out any GitHub-hosted private dependencies
Automatic git merging/tagging/etc

Private keys are also used to enable your project to check out additional private repositories.

User key security

CircleCI will never make your SSH keys public.

The private keys of the checkout key-pairs CircleCI generates never leave the CircleCI systems (only the public key is transmitted to GitHub) and are safely encrypted in storage. However, since the keys are installed into your build containers, any code that you run in CircleCI can read them. Likewise, developers that can SSH in will have direct access to this key.

Remember that SSH keys should be shared only with trusted users. GitHub collaborators on projects employing user keys can access your repositories, therefore, only entrust a user key to someone with whom you would entrust your source code.

Here are common errors that indicate you need to add a user key.

Python: During the pip install step:

ERROR: Repository not found.

Ruby: During the bundle install step:

Permission denied (publickey).

Add a `.circleci/config.yml` file

After the necessary permissions have been set up, the next step is adding a .circleci/config.yml file to the projects you would like to use with CircleCI. Add a .circleci directory to a repository you want to connect to CircleCI. Inside that directory, add a config.yml file.

After you create and commit a .circleci/config.yml file to your GitHub repository, CircleCI immediately checks your code out and runs your first job along with any configured tests.

CircleCI runs your tests on a clean container every time so that your tests are fresh each time you push code, and so that your code is never accessible to other users. Watch your tests update in real-time on your dashboard. You can also get status updates through email notifications, or look for the status badges that appear on GitHub. Integrated statuses also appear on the pull request screen, to show that all tests have passed.

See the Configuration tutorial page for a configuration walkthrough.

Enable your project to check out additional private repositories

If your testing process refers to multiple repositories, CircleCI will need a GitHub user key in addition to the deploy key because each deploy key is valid for only one repository, while a GitHub user key has access to all of your GitHub repositories.

Provide CircleCI with a GitHub user key in your project’s Project Settings > SSH keys. Scroll down the page to User Key and select Authorize with GitHub. CircleCI creates and associates this new SSH key with your GitHub user account for access to all your repositories.

Best practices for keys

Use Deploy Keys whenever possible.
When Deploy Keys cannot be used, Machine user keys must be used, and have their access restricted to the most limited set of repository and permissions necessary.
Never use non-Machine user keys (keys should be associated with the build, not with a specific person).
You must rotate the Deploy or User key as part of revoking user access to that repository.
1. After revoking the user’s access in GitHub, delete keys in GitHub.
2. Delete the keys in the CircleCI project.
3. Regenerate the keys in CircleCI project.
Ensure no developer has access to a build in a repository with a User Key that requires more access than they have.

Establish the authenticity of an SSH host

When using SSH keys to check out repositories, it may be necessary to add the fingerprints for GitHub to a "known hosts" file (~/.ssh/known_hosts) so that the executor can verify that the host it is connecting to is authentic. The checkout job step does this automatically, so you will need to run the following commands if you opt to use a custom checkout command:

mkdir -p ~/.ssh

echo 'github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
' >> ~/.ssh/known_hosts

SSH keys for servers can be fetched by running ssh-keyscan <host>, then adding the key that is prefixed with ssh-rsa to the known_hosts file of your job. You can see this in action here:

➜  ~ ssh-keyscan github.com
# github.com:22 SSH-2.0-babeld-439edbdb
github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
# github.com:22 SSH-2.0-babeld-439edbdb
# github.com:22 SSH-2.0-babeld-439edbdb
➜  ~ ✗

You can add the key to known_hosts by running the following command:

ssh-keyscan github.com >> ~/.ssh/known_hosts

Controlling access via a machine user

For fine-grained access to multiple repositories, it is best practice to create a machine user for your CircleCI projects. A machine user is a GitHub user that you create for running automated tasks. By using the SSH key of a machine user, you allow anyone with repository access to build, test, and deploy the project. Creating a machine user also reduces the risk of losing credentials linked to a single user.

To use the SSH key of a machine user, follow the steps below.

To perform these steps, the machine user must have admin access. When you have finished adding projects, you can revert the machine user to read-only access.

Create a machine user by following the instructions on GitHub.
Log in to GitHub as the machine user.
Log in to the CircleCI web app. When GitHub prompts you to authorize CircleCI, select Authorize application.
From the Projects page, follow all projects you want the machine user to have access to.
On the Project Settings > SSH keys page, under the User Key section, select Authorize With GitHub. This gives CircleCI permission to create and upload SSH keys to GitHub on behalf of the machine user.
After authorizing, navigate to the SSH keys page again, go to the User Key section, and select Add User Key, then Confirm User.

Now, CircleCI will use the machine user’s SSH key for any Git commands that run during your builds.

Third party applications

GitHub recently added the ability to approve third party application access on a per-organization level. Before this change, any member of an organization could authorize an application (generating an OAuth token associated with their GitHub user account), and the application could use that OAuth token to act on behalf of the user via the API, with whatever permissions were granted during the OAuth flow.

Now OAuth tokens will, by default, not have access to organization data when third party access restrictions are enabled. You must specifically request access on a per organization basis, either during the OAuth process or later, and an organization admin must approve the request.

If you are an owner or admin, you can enable third party access restrictions by visiting the Organization settings page on GitHub, and clicking the Settings button for that organization. Under the Third-party application access policy section, you can select the Setup application access restrictions button if you want to set up restrictions for third party applications.

You can read more about these settings and how to configure them in the GitHub documentation.

If you enable these restrictions on an organization for which CircleCI has been running builds, CircleCI will stop receiving push event hooks from GitHub, and will not build new pushes. API calls will also be denied, causing, for instance, re-builds of old builds to fail the source checkout. To get CircleCI working again, you will need to grant access to the CircleCI application.

How to re-enable CircleCI for a GitHub organization

This section describes how to re-enable CircleCI after enabling third-party application restrictions for a GitHub organization. Go to GitHub Settings, and in the Organization access section, you will have the option to request access if you are not an admin, or grant access if you are an admin.

Non-admin member workflow

If you are member of a GitHub organization (not an admin), select Request and a message will be sent to an admin of your organization. An admin will have to approve the request.
Select Request approval from owners to send an email to your organization’s owners.
While waiting for approval, you will see Access request pending next to your organization’s name.
If CircleCI has been approved by your organization, you will see a checkmark next to your organization’s name.

Admin owner workflow

If you are an owner of your organization (an admin), you may grant access to CircleCI by clicking on the Grant button.
You may be asked to confirm your password in order to authorize our app.
Once you’ve approved CircleCI, you will see a checkmark next to your organization’s name.

After access is granted, CircleCI should behave normally again.

Rename organizations and repositories

If you would like to rename your organization or repository, follow the Rename organizations and repositories guide to make sure you do not lose access to environment variables or contexts in the process.

Using GitHub App functionality alongside the GitHub OAuth app

CircleCI’s GitHub App integration offers increased control over which resources in your VCS CircleCI can access, and lets CircleCI access those resources in a more secure manner. Specifically:

You can choose to only allow the CircleCI GitHub App access to specific repositories within your GitHub organization.
The CircleCI GitHub App only asks for fine-grained permissions to access your resources.
The CircleCI GitHub App uses short-lived tokens when accessing your resources.

Some existing and future functionality on CircleCI, such as triggering a pipeline via a custom webhook, will only be available when using the more secure GitHub App integration. Despite only being available when using the GitHub App, this functionality is still usable by organizations that currently integrate with CircleCI’s GitHub OAuth App. The GitHub App and OAuth app can co-exist side-by-side in the same organization without needing to sacrifice any functionality that is not yet available to the GitHub App integration (such as scheduled pipelines) or needing to set up and migrate to a new organization.

Refer to our community forum for an example and known limitations.

Next steps

Suggest an edit to this page

Make a contribution

Learn how to contribute

Still need help?

Ask the CircleCI community

Join the research community

Visit our Support site