Documentation structure for LLMs (llms.txt)
CircleCI Logo

Users, organizations, and integrations guide

9 hours ago
Cloud Server

This guide explains the concepts of user, organization, and integration in CircleCI. After these concepts are covered, you can find out about the features available to you depending on your organization and pipeline type.

User accounts

When you log in to CircleCI you are logging in to your user account.

On CircleCI Server, you log in with your GitHub account. Your organizations are the GitHub organizations you belong to, imported automatically when you authorize CircleCI.

A CircleCI user account can be integrated with VCS user accounts via authorization.

Your GitHub OAuth app authorization is displayed in User Settings  Account Integrations, and managed in GitHub from your GitHub settings, under Applications.

Organizations

An organization in CircleCI is a top-level account that serves as a container for your team’s projects, settings, and permissions. On CircleCI Server, every organization is a github type organization, linked to an organization on GitHub.com or GitHub Enterprise through the GitHub OAuth app.

Each organization has its own settings, including security, integrations, and resource management, allowing you to coordinate and control your CI/CD processes across multiple projects and users.

The VCS Integration Overview page provides a full list of CircleCI features available for each organization and integration type.

Projects

Projects are created automatically from your GitHub repositories. Select "Projects" in the CircleCI web app to view your repositories. From here you have the option to:

  • Set up new repositories as CircleCI projects. Commit a CircleCI config.yml file to the repository to define your pipeline. This creates a GitHub OAuth pipeline for you, which you can view in Project Settings  Project Setup.

  • Follow/unfollow projects, to subscribe/unsubscribe from notifications for builds.

When you set up a project to build with 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 webhook that is used to notify CircleCI when you push to GitHub.

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

VCS integration

On CircleCI Server, CircleCI checks out your code from GitHub.com or GitHub Enterprise through the GitHub OAuth app integration. Your Server administrator sets up the GitHub OAuth app when installing CircleCI Server, so no additional action is required.

Organization user permissions

On CircleCI Server, user permissions are inherited from GitHub.

OAuth permissions

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

Pipelines

Pipelines are the highest-level unit of work in your CI/CD process. Pipelines orchestrate the execution of workflows which run jobs to build, test, and deploy your code.

Pipelines are defined by two characteristics:

  • A configuration source, stored in a repository.

  • A checkout source, which determines which repository will be checked out when running a Checkout Step.

The pipelines you can create and configure are derived from the integration types available to you. You can find this information in the VCS integration section.

On CircleCI Server, a pipeline is created automatically for each of your projects when the project is set up.

How CircleCI checks out your code

When you set up a new project with a GitHub OAuth pipeline, CircleCI creates a deployment key on the VCS provider for your project. A deploy key is an SSH key-pair, one public, one private. The VCS provider 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.

For code in GitHub, to set up a CircleCI project, you might find you need to enable the creation of deploy keys in your GitHub organization. To do so follow these steps:

  1. Log in to GitHub.com.

  2. Navigate to your organization.

  3. Select Settings at the top of the organization page.

  4. In the left sidebar, select "Deploy Keys" in the Security section.

  5. Enable the option for allow repositories in this organization to create deploy keys.

  6. Select Save.

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.

If your deploy keys or user keys appear to have been removed, it may be due to one of the following reasons:

  • GitHub will remove inactive keys if they are unused for over a year.

  • If CircleCI creates keys through a user’s OAuth integration with GitHub, and the user revokes or removes the integration, GitHub will also remove the associated keys.

  • In GitHub, if an organization owner restricts or disables deploy keys across all repositories, GitHub may disable or remove existing deploy keys.

  • If your CircleCI project has no followers, CircleCI will consider it disabled and remove the associated keys.

  • When you delete a CircleCI project, CircleCI will remove its associated keys.

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.

Custom checkout commands

CircleCI provides a checkout step that is used to check out your source code. You find more information about the special checkout step in the Configuration Reference page.

If you would rather use a custom checkout command, follow the steps below to ensure the authenticity of the host you are connecting to.

Establish the authenticity of an SSH host

When using SSH keys to check out a repository, it may be necessary to add the fingerprints for the VCS provider to a "known hosts" file (~/.ssh/known_hosts). Using known_hosts allows the executor to verify that the host it is connecting to is authentic. If you use the CircleCI checkout step, this is done automatically for you.

When using a custom checkout command you will need to run the following commands:

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

If you use GitHub Enterprise, use your GitHub Enterprise hostname in place of github.com in these commands.

Best practices for SSH keys

This section describes best practices for using SSH keys in your CircleCI pipelines.

  • 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. It is best practice for keys to 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. See the Rotate Project SSH Keys page for steps to rotate your keys.

  • Ensure no developer has access to a build in a repository with a User Key that requires more access than they have.

Create a user key

Create a user key in CircleCI when:

  • You need write access to your GitHub or Bitbucket repositories during your CI/CD pipeline.

  • When you need to access multiple repositories that your user account has access to.

Some example tasks where you might need a user key:

  • Pushing commits back to your repository. If your pipeline needs to commit and push changes back to GitHub, you need the write permissions that a user key provides. Common examples include updating a changelog, bumping version numbers, generating documentation, or creating automated pull requests.

  • Accessing multiple private repositories. When your build depends on multiple private repos (beyond just the one being built), a user key gives your pipeline access to all repos your GitHub user can access. A user key is useful for:

    • Pulling private dependencies from other repos your organization owns.

    • Checking out submodules from private repositories.

    • Running scripts that interact with multiple repos.

As described above, CircleCI automatically provides a deploy key for the repository being built, but deploy keys have some limitations:

  • Read-only by default.

  • Limited to a single repository.

  • Can not be reused across multiple repositories.

A user key bypasses these limitations.

The trade-off with choosing a user key is that user keys grant broad access based on your GitHub account’s permissions. User keys are a bigger security risk if compromised.

We recommend creating a dedicated "machine user" GitHub/Bitbucket account with minimal necessary permissions. Then add that machine user’s key to CircleCI, rather than using your personal GitHub/Bitbucket account’s key.

To create a user key, follow these steps:

To use the recommended machine-user approach, create a new GitHub/Bitbucket account with minimal necessary permissions. Then follow these steps while logged in as that machine user account.

  1. In the CircleCI web app, select your org from the org cards on your user homepage.

  2. Select Projects from the sidebar and locate your project from the list. You can use the search to help.

  3. Select the ellipsis Ellipsis menu iconEllipsis menu icon next to your project and select Project Settings.

    You can also access project settings from each project overview page using the Settings button.

  4. In the sidebar menu, select SSH Keys.

  5. Under the User Key section, select Add User Key.

  6. You will see a warning to use a machine user. Select Confirm User.

  7. You will now see your user key displayed on the page.

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

Create additional SSH keys - All pipeline types

You may need to add additional SSH keys to your pipelines. Some examples of when you might need to add additional SSH keys are as follows:

  • Secure authentication to remote systems. SSH keys allow your pipeline to authenticate to servers, repositories, or services without storing plaintext passwords. That kind of authentication is crucial when you need to deploy code to production servers, pull from private repositories, or interact with remote infrastructure.

  • Git operations with private repositories. Many projects depend on private packages or modules hosted in private Git repositories. SSH keys enable your CI/CD pipeline to clone these dependencies during the build process.

  • Automated deployments. When deploying applications, pipelines often need to SSH into servers to transfer files, restart services, or run deployment scripts. SSH keys make this automation possible without manual intervention or exposing credentials.

  • Third-party service integration. Some services and tools require SSH authentication for secure communication. For example, interacting with certain package registries, backup systems, or specialized deployment tools may require SSH key authentication.

If you need additional SSH keys in your builds, follow these steps:

In this example you will create a deploy key with write access to a GitHub repository. The GitHub repository is https://github.com/you/test-repo, and the CircleCI project is https://app.circleci.com/pipelines/github/you/test-repo.

  1. 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"

  2. 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.

  3. 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.

  4. 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.

If you use GitHub Enterprise, enter your GitHub Enterprise hostname in the "hostname" field in place of github.com. In the example, replace app.circleci.com with your CircleCI Server hostname.

For a guide to additional SSH keys for CircleCI pipelines, see the Add SSH Keys page.

Controlling access via a machine user

For fine-grained access to multiple repositories, it is best practice to create a non-human user for your CircleCI projects. For example, 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.

  1. Create a machine user by following the instructions on GitHub.

  2. Log in to GitHub as the machine user.

  3. Log in to the CircleCI web app for your Server installation. When GitHub prompts you to authorize CircleCI, select Authorize application.

  4. From the Projects page, follow all projects you want the machine user to have access to.

  5. 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.

  6. 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.

Built-in environment variables and pipeline values

The built-in environment variables and pipeline values available to you depend on your project integration type. For a full list see the Project Values and Variables page.

Feature support

Some organization and project combinations affect the features that are available to you. For a full list, see the Version Control System Integration Overview page.

Troubleshooting

GitHub third party application restrictions for OAuth integrations

GitHub provides the ability to approve third party application access on a per-organization level.

Before GitHub added this option the following was true:

  • Any member of an organization could authorize an application (generating an OAuth token associated with their GitHub user account).

  • The application could use that OAuth token to act on behalf of the user via the API, with whatever permissions granted during the OAuth flow.

OAuth tokens will now, 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 a GitHub organization owner or admin, you can enable third party access restrictions. For steps see the GitHub docs

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. In your GitHub settings, select Applications, then the Authorized OAuth Apps tab, and select the CircleCI OAuth app that your Server administrator set up. In the Organization access section, you will have the option to:

  • Request access if you are not an admin.

  • 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 have approved CircleCI, you will see a checkmark next to your organization’s name.

After access is granted, CircleCI will behave normally again.

Disconnect a GitHub OAuth or Bitbucket Cloud account from your user account

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/Bitbucket user account.

  • Changes to the organization name in your VCS.

Follow these steps to disconnect your CircleCI account from GitHub.

  1. From the CircleCI web app, navigate to your User Settings by clicking on your user icon in the top bar.

  2. Select Account Integrations.

  3. You will see a list of connections along with the GitHub or Bitbucket organizations they are associated with. Select Disconnect next to the GitHub/Bitbucket connection you wish to disconnect.

Once disconnected, you will be redirected to the CircleCI login page. To reconnect your account, log in to CircleCI using your GitHub or Bitbucket social login credentials.

Frequently asked questions

The following are common questions about managing your user account and organizations in CircleCI.

How can I enable my project to check out additional private repositories?

For github and bitbucket organizations, you can enable your project to check out additional private repositories by adding a user key or additional SSH key to your project. See the Create a user key section of this page for instructions.

For circleci, github and bitbucket organizations, you can enable your project to check out additional private repositories by adding an additional SSH key to your project. See the Create additional SSH keys - All pipeline types section of this page for instructions.