--- title: "Set up VCS connections" description: "Connect your CircleCI organization to a version control system provider, and view, configure, or remove existing connections." doc_version: "unversioned" last_updated: "2026-09-01" --- > For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt) # Set up VCS connections A VCS connection is what gives CircleCI access to the code in your repositories. It links your CircleCI organization to your version control system (VCS) provider. CircleCI can then check out your code, and receive events from your repositories such as a push or a pull request. You manage these connections at **Org**  **VCS Connections** in the CircleCI web app. You can also install a connection while creating a project. If you would rather set your connection up as part of that flow, see the [Create a Project](https://circleci.com/docs/guides/getting-started/create-project/) page. For which connections are available to your organization type, and which features each supports, see the [Users, Organizations, and Integrations Guide](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/#vcs-integration) and the [VCS, Pipeline Types, and Feature Support](https://circleci.com/docs/guides/integration/version-control-system-integration-overview/) page. ## View your connections The **Org**  **VCS Connections** page has two parts: * **Connected** lists the providers your organization is already connected to. Expand a connection to see the permissions it has been granted and which repositories it can access. Each connection also has controls to configure or remove it. * **Available Providers** shows the providers you can still connect, as a set of cards. Select a provider card to start installing that connection. Some connections need extra configuration before pipelines can run. For example, a self-managed provider may show a prompt to add `known_hosts` values. The tabs in the next section cover what each provider requires. ## Removing a connection is not deleting an org or project Removing a VCS connection and deleting a CircleCI organization or project are separate actions, and what happens to your organization depends on the provider: * For `circleci` type organizations, the connection is an add-on. Removing it leaves your organization and projects in place. * For `github` and `bitbucket` type organizations, the organization exists **because** of the OAuth connection. Disconnecting GitHub OAuth or Bitbucket Cloud removes that organization from CircleCI. Check the tab for your provider below before removing a connection. To delete an organization or project itself, see the [Delete Organizations and Projects](https://circleci.com/docs/guides/security/delete-organizations-and-projects/) page. ## Connect a provider The following tabs describe your options for each integration type. Select the tab for the provider you want to connect. How you start depends on the provider. GitLab self-managed and Bitbucket Data Center use a **Set up integration** button, while other providers are shown as cards under "Available Providers". **Availability**: A GitHub App integration is available for `circleci` and `github` type organizations. The CircleCI GitHub App is installed into an organization. The GitHub App integration supports GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server. GitHub Enterprise Server support is currently in Preview. See the [GitHub Enterprise Server Integration](https://circleci.com/docs/guides/integration/github-enterprise-server-integration/) page for more information. **View**: To view a GitHub App integration, navigate to **Org**  **VCS Connections**. If you are in a `circleci` or `github` organization you will either see your active GitHub App integration or an option to install the GitHub App. **Disconnect**: To **uninstall** the GitHub App from your organization, select the trash/bin button and follow the instructions. **Availability**: A GitHub OAuth app integration is installed into a `github` type organization. **View**: To **view** a GitHub OAuth app integration, navigate to **Org**  **VCS Connections**. If the GitHub OAuth app is installed you will see this indicated in the OAuth app section. **Disconnect**: You can _disconnect_ your GitHub OAuth app integration. Doing so will remove your `github` organization from CircleCI. To disconnect your GitHub OAuth app integration, navigate to **User Settings**  **Account Integrations**, select **Disconnect** next to your GitHub integration and follow the instructions. **Availability**: A Bitbucket Cloud integration is installed into a `bitbucket` type organization. **View**: To **view** a Bitbucket Cloud integration, navigate to **Org**  **VCS Connections**. If the Bitbucket Cloud integration is installed you will see this indicated in the Bitbucket Cloud section. **Disconnect**: You can _disconnect_ your Bitbucket Cloud integration. Doing so will remove your `bitbucket` type organization from CircleCI. To disconnect your Bitbucket Cloud integration, navigate to **User Settings**  **Account Integrations**, select **Disconnect** next to your Bitbucket Cloud integration and follow the instructions. **Availability**: A GitLab SaaS integration is installed into a `circleci` type organization. **View**: Currently, there is no method to manage the connection with GitLab outside of the project setup, trigger, and configuration settings. **Disconnect**: Currently, there is no method to disconnect GitLab from your organization. You can delete projects that are connected to GitLab, and delete the CircleCI webhooks in GitLab to achieve this. See the [Delete Organizations and Projects](https://circleci.com/docs/guides/security/delete-organizations-and-projects/) page for more information. If you use both CircleCI’s Bitbucket Data Center and GitLab self-managed integrations, be aware of a known bug in **Org**  **VCS Connections**. Adding a `known_hosts` value to one integration also populates the `known_hosts` field for the other integration. To use both integrations in the same CircleCI organization, add both `known_hosts` values to the single input field, separated by a new line. **Availability**: A GitLab self-managed integration is installed into a `circleci` type organization. **Configure**: Set up an integration with your GitLab self-managed instance from **Org**  **VCS Connections** as follows: 1. Select **Set Up Integration** next to GitLab self-managed. 2. Enter your GitLab self-managed instance URL, for example, `[https://test-gitlab.circleci.com](https://test-gitlab.circleci.com)`. Your self-managed instance must already contain at least one GitLab project — the authorization attempt fails if your instance has no projects. The self-managed instance must also be accessible via the public internet. If it is behind a firewall, see [a suggested workaround](https://discuss.circleci.com/t/gitlab-self-managed-support-on-circleci-is-now-here/47726/3?u=sebastian-lerner). 3. Enter your instance’s SSH public host keys. You can retrieve this from your instance by running `ssh-keyscan `, for example, `ssh-keyscan test-gitlab.circleci.com`, and copying the command’s output. The output looks something like: ```shell ➜ ~ ssh-keyscan test-gitlab.circleci.com # gitlab.com:22 SSH-2.0-GitLab-SSHD gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9 # gitlab.com:22 SSH-2.0-GitLab-SSHD gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY= # gitlab.com:22 SSH-2.0-GitLab-SSHD gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf # gitlab.com:22 SSH-2.0-GitLab-SSHD # gitlab.com:22 SSH-2.0-GitLab-SSHD ``` 4. Select **Set Up Integration**. To create pipelines for your code in GitLab self-managed, you will need to generate a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html). This token must have the `api` scope. You cannot currently edit or delete existing GitLab self-managed integrations. **View**: Currently, there is no method to manage the connection with GitLab self-managed outside of the project setup, trigger, and configuration settings. **Disconnect**: Currently, there is no method to disconnect GitLab self-managed from your organization. You can delete projects that are connected to GitLab self-managed and delete the CircleCI webhooks in GitLab to achieve this. See the [Delete Organizations and Projects](https://circleci.com/docs/guides/security/delete-organizations-and-projects/) page for more information. If you use both CircleCI’s Bitbucket Data Center and GitLab self-managed integrations, be aware of a known bug in **Org**  **VCS Connections**. Adding a `known_hosts` value to one integration also populates the `known_hosts` field for the other integration. To use both integrations in the same CircleCI organization, add both `known_hosts` values to the single input field, separated by a new line. **Availability**: A Bitbucket Data Center integration is installed into a `circleci` type organization. **Configure**: Set up an integration with your Bitbucket Data Center instance from **Org**  **VCS Connections** as follows: 1. Select **Set up integration** next to Bitbucket Data Center. 2. In the modal enter your Bitbucket Data Center instance URL and your `known_hosts`: Integrating CircleCI with your Bitbucket Data Center instance requires that you store a public SSH host key within the CircleCI organization that will be accessing the Bitbucket Data Center instance. To get the required SSH host key, run `ssh-keyscan` with the hostname and port of your Bitbucket Data Center instance. For example: Replace the port with the correct port for your instance, and the hostname with your Bitbucket Data Center hostname. ```shell ssh-keyscan -p 1234 bitbucket-datacenter.example.com ``` The output will look something like the following: ```shell [bitbucket-datacenter.example.com]:1234 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAA//NF6iU86j0hfGxn8ncjgwvmk9tMKzhFqrRLaltP0TGt760PhfWk070raKLHS3L6H0BdN9qNVsTk63czziFDmtBehE82/XXX+59MuppY0DHG3brNvw4REPmzZkQNIR6Cs8b15iFbwnIL51IH9kBVMztWQaRDPkPPxihM6e0n/vo5n3uEIPCTZiwLgKRcpeks2LsfbsW0NN5Q7J1Irp/ACstfrsFWSntranbjMe6cIwELNY6FhvYmETzH0cY0= ``` Copy the full output from the `ssh-keyscan` command and enter it into the "known hosts" text box when setting up your integration in the CircleCI web app under **Org**  **VCS Connections**. 3. Select **Set Up Integration**. To set up Bitbucket data center pipelines you will need to create a project HTTP access token with the project admin scope. Create this under Projects in Bitbucket. For more information, see the [Bitbucket docs](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html). Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI. **View**: Currently, there is no method to manage the connection with Bitbucket Data Center outside of the project setup, trigger, and configuration settings. **Disconnect**: Currently, there is no method to disconnect Bitbucket Data Center from your organization. You can delete projects that are connected to Bitbucket Data Center and delete the CircleCI webhooks in Bitbucket Data Center to achieve this. See the [Delete Organizations and Projects](https://circleci.com/docs/guides/security/delete-organizations-and-projects/) page for more information. The Cursor Origin integration is in beta. **Availability**: A Cursor Origin integration is installed into a `circleci` type organization. Cursor Origin is Cursor’s git forge for storing and sharing code. For more information, see the [Cursor Origin documentation](https://cursor.com/docs/origin). **Configure**: From **Org**  **VCS Connections**, select the **Cursor Origin** card under "Available Providers". Follow the instructions to install and authorize the CircleCI app in your Origin codebase. You are also walked through this installation when you create your first Cursor Origin project. See the [Create a Project](https://circleci.com/docs/guides/getting-started/create-project/#create-a-project) page for those steps. **View**: To view a Cursor Origin integration, navigate to **Org**  **VCS Connections**. **Triggers**: For the trigger events available to Cursor Origin pipelines, see the [Cursor Origin Trigger Event Options](https://circleci.com/docs/guides/orchestrate/cursor-origin-trigger-event-options/) page. **Disconnect**: You can remove a Cursor Origin connection from **Org**  **VCS Connections**, or uninstall the CircleCI app from the Origin side. Removing the connection does not delete your CircleCI organization or your projects. ## Can multiple CircleCI organizations connect to the same GitHub organization? A GitHub organization can only be connected via CircleCI GitHub App to a single CircleCI organization. If you attempt to connect your CircleCI organization to a GitHub organization that already has the CircleCI GitHub App installed, you will be redirected to the GitHub App installation page. You will not be redirected back to CircleCI. This can be confusing because GitHub will show a successful installation. That installation, however, refers to the existing connection to a different CircleCI organization, not the one you just tried to create. You can confirm this by checking the "installed at" date at the top of the page. Unfortunately, GitHub doesn’t indicate which CircleCI organization is already connected, so if you need help identifying the existing connection, you can submit a request [by filling out this form](https://forms.gle/dvcXN8ArByXqNNbJ7). > **Image:** Create a project Figure 1. GitHub settings showing the CircleCI App integration settings page.