--- title: "Users, organizations, and integrations guide" description: "A guide to understanding user accounts, organizations and integrations with version control systems in CircleCI." platform: "Cloud, Server" doc_version: "Server" last_updated: "2026-10-26" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Users, organizations, and integrations guide 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](https://circleci.com/docs/guides/integration/version-control-system-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](https://developer.github.com/v3/oauth/#scopes). **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](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/#available-scopes), 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](https://circleci.com/docs/reference/configuration-reference/#checkout). 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](#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](https://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](https://circleci.com/docs/reference/configuration-reference/#checkout) 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: ```shell 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 `, 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: ```shell ➜ ~ 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: ```shell 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](#controlling-access-via-a-machine-user) 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](https://circleci.com/docs/guides/server/security/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 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. ### User key access-related error messages 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](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/). When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): ```console $ 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: ```yaml 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](https://circleci.com/docs/guides/server/integration/add-ssh-key/) 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](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) 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](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users). 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](https://circleci.com/docs/reference/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](https://circleci.com/docs/guides/server/integration/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](https://help.github.com/articles/about-third-party-application-restrictions/). 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](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/enabling-oauth-app-access-restrictions-for-your-organization) 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](#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](#create-additional-ssh-keys) section of this page for instructions.