From 6e119bbec135b0bf1d5113e73f249d2896774679 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Mon, 20 Oct 2025 14:44:54 +0100 Subject: [PATCH 01/23] start new consolidated page --- ...-organizations-and-integrations-guide.adoc | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc new file mode 100644 index 0000000000..ae901e9787 --- /dev/null +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -0,0 +1,39 @@ += Users, organizations, and integrations guide +:page-platform: Cloud +:page-description: A guide to understanding user accounts, organizations and integrations with version control systems in CircleCI. +:experimental: + +The guide defines the concepts of user, organization and integration in CircleCI. After these concepts are covered you will find out about the features available to you depending on you organization and pipeline type. + +== User account + +When you log in to CircleCI you are logging in to your user account. + +#user settings# + +As a CircleCI _user_ you can have access to zero, one or many _organizations_. + +There are two ways to log in to CircleCI: + +* Email and password +* Social login (GitHub, Bitbucket) + +== Organizations + +An organization in CircleCI is a workspace that serves as a container for your team's projects, settings, permissions, and billing. Organizations are typically linked to your version control system (VCS) account(s), such as GitHub, GitLab, or Bitbucket. + +Creating an organization allows you to manage the following: + +* Multiple projects under a single entity. +* Configure and manage CI/CD pipelines specific to your team or company needs. +* Invite team members. +* Assign roles (`circleci` orgs only). + +Each organization has its own settings, including security, integrations, and resource management, making it easier to coordinate and control your CI/CD processes across multiple projects and users. + +A CircleCI _organization_ can be one of three types: + +A CircleCI `circleci` organization:: You can create a `circleci` organization from your user homepage. #create guide to making a new org and link to it - retire support article?# +* A CircleCI `github` organization:: #do we want to cover setting up one of these?# +* A CircleCI `bitbucket` organization + From 9e9e4a4aeeb03ef32396a178d4219eea980ffb7b Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Mon, 20 Oct 2025 22:24:48 +0100 Subject: [PATCH 02/23] add new page to nav --- docs/guides/modules/ROOT/nav.adoc | 1 + ...ers-organizations-and-integrations-guide.adoc | 16 ++++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/docs/guides/modules/ROOT/nav.adoc b/docs/guides/modules/ROOT/nav.adoc index 3036399193..8761508936 100644 --- a/docs/guides/modules/ROOT/nav.adoc +++ b/docs/guides/modules/ROOT/nav.adoc @@ -217,6 +217,7 @@ ** xref:insights:insights-glossary.adoc[Insights glossary] * Manage roles, permissions, and authentication +** xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide] ** Roles and permissions *** xref:permissions-authentication:roles-and-permissions-overview.adoc[Roles and permissions overview] *** xref:permissions-authentication:manage-roles-and-permissions.adoc[Manage roles and permissions] diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index ae901e9787..2ad5063dfd 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -37,3 +37,19 @@ A CircleCI `circleci` organization:: You can create a `circleci` organization fr * A CircleCI `github` organization:: #do we want to cover setting up one of these?# * A CircleCI `bitbucket` organization +== Integration options + +The integration options available to you depend on your organization type, as follows: + +[cols=7*, options="header"] +|=== +| Organization type |Github App | GitHub OAuth | Bitbucket Cloud | Bitbucket Data Center | GitLab self managed | GitLab SaaS + +| `circleci` +| [.circle-green]#Yes# +| [.circle-green]#Yes# +| [.circle-green]#Yes# +| [.circle-green]#Yes# +| [.circle-green]#Yes# +| [.circle-green]#Yes# +|=== \ No newline at end of file From 75772ffbac1967f06c0a734ded3bf5d6366c332a Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Wed, 22 Oct 2025 18:43:14 +0100 Subject: [PATCH 03/23] more work on a consolidated page --- ...-organizations-and-integrations-guide.adoc | 97 ++++++++++++++++--- 1 file changed, 84 insertions(+), 13 deletions(-) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 2ad5063dfd..b64f17759a 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -3,39 +3,43 @@ :page-description: A guide to understanding user accounts, organizations and integrations with version control systems in CircleCI. :experimental: -The guide defines the concepts of user, organization and integration in CircleCI. After these concepts are covered you will find out about the features available to you depending on you organization and pipeline type. +This guide defines the concepts of user, organization and integration in CircleCI. After these concepts are covered you will find out about the features available to you depending on you organization and pipeline type. == User account -When you log in to CircleCI you are logging in to your user account. +When you log in to CircleCI you are logging in to your _user account_. #user settings# -As a CircleCI _user_ you can have access to zero, one or many _organizations_. +As a CircleCI _user_ you can access _organizations_. You can have access to zero, one or many organizations. There are two ways to log in to CircleCI: * Email and password * Social login (GitHub, Bitbucket) +#INSTRUCTION FOR DELETING A USERT ACCOUNT?# + == Organizations -An organization in CircleCI is a workspace that serves as a container for your team's projects, settings, permissions, and billing. Organizations are typically linked to your version control system (VCS) account(s), such as GitHub, GitLab, or Bitbucket. +An organization in CircleCI is a workspace that serves as a container for your team's projects, settings, permissions, and billing. Organizations are typically linked to your version control system (VCS) account(s) (GitHub, GitLab, or Bitbucket). -Creating an organization allows you to manage the following: +Create an organization allows you to manage the following: * Multiple projects under a single entity. -* Configure and manage CI/CD pipelines specific to your team or company needs. -* Invite team members. -* Assign roles (`circleci` orgs only). +* CI/CD pipelines specific to your team or company needs. +* Invites for team members. +* Assignment of roles (`circleci` orgs only, roles for `github` and `bitbucket` orgs are managed through the VCS provider). Each organization has its own settings, including security, integrations, and resource management, making it easier to coordinate and control your CI/CD processes across multiple projects and users. A CircleCI _organization_ can be one of three types: -A CircleCI `circleci` organization:: You can create a `circleci` organization from your user homepage. #create guide to making a new org and link to it - retire support article?# -* A CircleCI `github` organization:: #do we want to cover setting up one of these?# -* A CircleCI `bitbucket` organization +A CircleCI `circleci` organization:: You can create a `circleci` organization from your user homepage via the btn:[Create organization] button. #create guide to making a new org and link to it - retire support article?# +A CircleCI `github` organization:: A `github` organization used an OAuth app connection and is created when you log in to CircleCI using your GitHub account, rather than using your email/password or by connecting to GitHub Oauth app via menu:User Settings[Application Integrations]. #do we want to cover setting up one of these?# +A CircleCI `bitbucket` organization:: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account, rather than using your email/password or by connecting to Bitbucket OAuth app via menu:User Settings[Application Integrations].#do we want to cover setting up one of these?# + +For a guide to creating an organization, see #Add link when ready# == Integration options @@ -43,13 +47,80 @@ The integration options available to you depend on your organization type, as fo [cols=7*, options="header"] |=== -| Organization type |Github App | GitHub OAuth | Bitbucket Cloud | Bitbucket Data Center | GitLab self managed | GitLab SaaS +| Organization type |GitHub App | GitHub OAuth | Bitbucket Cloud | Bitbucket Data Center | GitLab self managed | GitLab SaaS | `circleci` | [.circle-green]#Yes# +| [.circle-red]#No# +| [.circle-red]#No# | [.circle-green]#Yes# | [.circle-green]#Yes# | [.circle-green]#Yes# + +|`github` +| [.circle-green]#Yes# | [.circle-green]#Yes# +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-red]#No# + +|`bitbucket` +| [.circle-red]#No# +| [.circle-red]#No# | [.circle-green]#Yes# -|=== \ No newline at end of file +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-red]#No# + +|=== + +== View and manage integrations + +You can view and manage integrations in two places depending on your organization type. The following sections describe your options for each integration type. + +=== Manage a GitHub App integration + +A GitHub App integration is available for `circleci` and `github` organizations. The CircleCI GitHub App is installed in an organization. To see your integration navigate to menu:Organization Settings[Account Integrations]. 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. + +If you would like to uninstall the GitHub App, select the trash/bin button and follow the instructions. + +=== Manage a GitHub OAuth app integration + +A GitHub OAuth app integration is built into a `github` type organization. + +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 menu:User Settings[Account Integrations], select btn:[Disconnect] next to your GitHub integration and follow the instructions. + +=== Manage a Bitbucket Cloud integration + +A Bitbucket Cloud integration is built into a `bitbucket` type organization. + +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 menu:User Settings[Account Integrations], select btn:[Disconnect] next to your Bitbucket Cloud integration and follow the instructions. + +##GITLAB BBDC REMOVAL INSTRUCTIONS?# + +== Invite your team to your organization + +#Add instructions for inviting for each org type# + +== Organization user permissions + +For `github` and `bitbucket` type organizations user permissions are inherited from the VCS provider. + +For `circleci` type organizations user permissions are managed through CircleCI. You can find information on managing organization and project roles and permissions starting with the xref:permissions-authentication:roles-and-permissions-overview.adoc[Roles and Permissions] page. You can manage roles and permissions at an organization and project level. You can manage roles and permissions individually for each user or add users to groups and manage group roles and permissions. + +== Projects + +== Pipelines + +== Rename an organization or project + +For full instructions on renaming organizations and projects, see the xref:security:rename-organizations-and-repositories.adoc[Rename organizations and projects] page. + +== Delete and organization or project + +For full instructions on deleting organizations and projects, see the xref:security:delete-organizations-and-projects.adoc[Delete organizations and repositories] page. + +== Feature support + + From 72ab3c4794435a030a81c355dcc0dc26ce4af5b1 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Wed, 22 Oct 2025 23:01:11 +0100 Subject: [PATCH 04/23] more work on bringing integration content together --- ...-organizations-and-integrations-guide.adoc | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index b64f17759a..e1a56fce6c 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -121,6 +121,117 @@ For full instructions on renaming organizations and projects, see the xref:secur For full instructions on deleting organizations and projects, see the xref:security:delete-organizations-and-projects.adoc[Delete organizations and repositories] page. +== How CircleCI checks out your code + +The way your code is checked out when a pipeline is triggered depends on the pipeline type you have set up. The different methods are described below. + +=== GitHub OAuth and Bibucket Cloud pipelines + +When you set up a new project with a GitHub OAuth or Bitbucket Cloud pipelines, 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: + +. Log in to link:https://github.com[GitHub.com]. +. Navigate to your organization. +. Click on Settings at the top of the organization page. +. In the left sidebar, select "Deploy Keys" in the Security section. +. Enable the option for allow repositories in this organization to create deploy keys. +. Select btn:[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 xref:about-circleci:introduction-to-the-circleci-web-app.adoc#projects[followers], CircleCI will consider it disabled and remove the associated keys. +* When you delete a CircleCI project, CircleCI will remove its associated keys. +**** + +[#create-a-github-user-key] +=== Create a GitHub user key + +To create a GitHub user key, follow these steps: + +include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[] + +. In the sidebar menu, select *SSH Keys*. +. Under the **User Key** section, select btn:[Authorize With GitHub]. The page will refresh while the authorization takes place and you will be redirected back to the project settings overview page. +. Navigate back to **SSH keys** and go to the **User Key** section. +. Select btn:[Add User Key], then btn:[Confirm User]. You will now see your user key displayed on the page. + +[#create-additional-github-ssh-keys] +=== 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 link:https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/[GitHub instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): ++ +```shell + 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: ++ +```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. + +[#how-are-private-keys-used] +=== 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 <<#enable-your-project-to-check-out-additional-private-repositories,check out additional private repositories>>. + +[#user-key-security] +=== 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. + +[#user-key-access-related-error-messages] +=== 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). +``` + == Feature support From e30f9fe944463b1e703453fff04f219179975f0c Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Thu, 23 Oct 2025 15:00:26 +0100 Subject: [PATCH 05/23] bringing in more content to consolidated page --- ...-organizations-and-integrations-guide.adoc | 209 ++++++++++++++---- 1 file changed, 164 insertions(+), 45 deletions(-) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index e1a56fce6c..1877391e81 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -109,9 +109,17 @@ For `github` and `bitbucket` type organizations user permissions are inherited f For `circleci` type organizations user permissions are managed through CircleCI. You can find information on managing organization and project roles and permissions starting with the xref:permissions-authentication:roles-and-permissions-overview.adoc[Roles and Permissions] page. You can manage roles and permissions at an organization and project level. You can manage roles and permissions individually for each user or add users to groups and manage group roles and permissions. -== Projects +== Projects and pipelines -== Pipelines +For `github` and `bitbucket` type organizations projects are synonymous with repositories. Select "Projects" in the link:https://app.circleci.com/home[CircleCI web app] to view your repositories. From here you have the option to: + +* Set up new repositories as CircleCI projects, which involves committing a CircleCI `config.yml` file to the repository to define your pipeline. THis creates a GitHub OAuth or Bitbucket Cloud pipeline for you, which you can view in menu:Project Settings[Project Setup] or menu:Project Settings[Pipelines] . +* Follow/unfollow projects, to subscribe/unsubscribe from notifications for builds. + +For `circleci` type organizations, projects are created separately to code repositories directly in CIrcleCI via the web app, API or CLI. Select "Projects" in the link:https://app.circleci.com/home[CircleCI web app] to view your projects. From here you have the option to: + +* Create a new project, including setting up a pipeline, at which point you connect your code repository to your project. +* Follow/unfollow projects, to subscribe/unsubscribe from notifications for builds. == Rename an organization or project @@ -121,13 +129,55 @@ For full instructions on renaming organizations and projects, see the xref:secur For full instructions on deleting organizations and projects, see the xref:security:delete-organizations-and-projects.adoc[Delete organizations and repositories] page. -== How CircleCI checks out your code +== Triggers -The way your code is checked out when a pipeline is triggered depends on the pipeline type you have set up. The different methods are described below. +The trigger options available to you depend on your pipeline type. These options are described in the following table: -=== GitHub OAuth and Bibucket Cloud pipelines +[options="header",cols="1,1,1,1,1,1,1,1"] +|=== +|Pipeline type +^|GitHub OAuth trigger +^|Bitbucket CloudOAuth trigger +^|GitLab trigger +^|Schedule trigger +^|GitHub App trigger +^|Custom Webhook +^|API / Manual triggering + +|GitHub OAuth image:guides:ROOT:icons/github-oauth.svg[OAuth pipeline badge, role="no-border"] +^|Zero or one +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|Zero, one, many +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|[.circle-green]#*Yes*# + +|GitHub App image:guides:ROOT:icons/github-app.svg[GitHub App pipeline badge, role="no-border"] +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|Zero, one, many +^|Zero, one, many +^|Zero, one, many +^|[.circle-green]#*Yes*# +|=== -When you set up a new project with a GitHub OAuth or Bitbucket Cloud pipelines, 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. +== How CircleCI checks out your code + +The way your code is checked out when a pipeline triggers depends on the pipeline type you have set up. The different methods are described below. Select the tab for your pipeline type to view information relevant to you. + +[tabs] +==== +GitHub App:: ++ +-- +#TBC# +-- +GitHub OAuth:: ++ +-- +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: @@ -150,61 +200,88 @@ If your deploy keys or user keys appear to have been removed, it may be due to o * When you delete a CircleCI project, CircleCI will remove its associated keys. **** -[#create-a-github-user-key] -=== Create a GitHub user key +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: -To create a GitHub user key, follow these steps: +- Checking out the main project +- Checking out any GitHub-hosted submodules +- Checking out any GitHub-hosted private dependencies +- Automatic git merging/tagging/etc -include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[] +Private keys are also used to enable your project to <<#enable-your-project-to-check-out-additional-private-repositories,check out additional private repositories>>. +-- +Bitbucket Cloud:: ++ +-- +When you set up a new project with a Bitbucket Cloud 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. -. In the sidebar menu, select *SSH Keys*. -. Under the **User Key** section, select btn:[Authorize With GitHub]. The page will refresh while the authorization takes place and you will be redirected back to the project settings overview page. -. Navigate back to **SSH keys** and go to the **User Key** section. -. Select btn:[Add User Key], then btn:[Confirm User]. You will now see your user key displayed on the page. +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. -[#create-additional-github-ssh-keys] -=== Create additional GitHub SSH keys +**** +If your deploy keys or user keys appear to have been removed, it may be due to one of the following reasons: -If you need additional SSH keys to access other services, you can create additional keys by following the steps below. +* 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 xref:about-circleci:introduction-to-the-circleci-web-app.adoc#projects[followers], CircleCI will consider it disabled and remove the associated keys. +* When you delete a CircleCI project, CircleCI will remove its associated keys. +**** -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`. +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: -. Create an SSH key-pair by following the link:https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/[GitHub instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): +- Checking out the main project +- Checking out any Bitbucket-hosted submodules +- Checking out any Bitbucket-hosted private dependencies +- Automatic git merging/tagging/etc + +Private keys are also used to enable your project to <<#enable-your-project-to-check-out-additional-private-repositories,check out additional private repositories>>. +-- +GitLab:: + -```shell - ssh-keygen -t ed25519 -C "your_email@example.com" -``` +-- +#TBC# +-- +Bitbucket Data Center:: ++ +-- +#TBC# +-- +==== -. 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**. +[#create-a-github-user-key] +== Create a GitHub user key - GitHub OAuth and Bitbucket Cloud pipelines only -. 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**. +Create a GitHub user key in CircleCI when you need write access to your GitHub repositories during your CI/CD pipeline, or when you need to access multiple repositories that your user account has access to. -. In your `.circleci/config.yml` file, add the fingerprint to a job using the `add_ssh_keys` key: -+ -```yaml - version: 2.1 +Some example tasks where you might need a GitHub user key: - jobs: - deploy-job: - steps: - - add_ssh_keys: - fingerprints: - - "SO:ME:FIN:G:ER:PR:IN:T" -``` +* Pushing commits back to your repository. If your pipeline needs to commit and push changes back to GitHub (like updating a changelog, bumping version numbers, generating documentation, or creating automated pull requests) you need write permissions that a user key provides. +* 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. This 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. -When you push to your GitHub repository from a job, CircleCI will use the SSH key you added. +As described above, CircleCI automatically provides a deploy key for the repository being built, but deploy keys have some limitations: -[#how-are-private-keys-used] -=== How are private keys used? +* Read-only by default. +* Limited to a single repository. +* Can not be reused across multiple repositories. -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: +A user key bypasses these limitations. -- Checking out the main project -- Checking out any GitHub-hosted submodules -- Checking out any GitHub-hosted private dependencies -- Automatic git merging/tagging/etc +The trade-off with chosing a user key is that user keys grant broad access based on your GitHub account's permissions, so they are a bigger security risk if compromised. -Private keys are also used to enable your project to <<#enable-your-project-to-check-out-additional-private-repositories,check out additional private repositories>>. +We recommend creating a dedicated "machine user" GitHub/Bitbucket account with minimal necessary permissions, then adding that account's user key to CircleCI, rather than using your personal GitHub/Bitbucket account's key. + +To create a GitHub user key, follow these steps: + +NOTE: To use the recommended approach of creating a machine user, you will need to create a new GitHub/Bitbucket account with minimal necessary permissions and then follow these steps logged in as that machine user account. + +include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[] + +. In the sidebar menu, select *SSH Keys*. +. Under the **User Key** section, select btn:[Authorize With GitHub]. The page will refresh while the authorization takes place and you will be redirected back to the project settings overview page. +. Navigate back to **SSH keys** and go to the **User Key** section. +. Select btn:[Add User Key], then btn:[Confirm User]. You will now see your user key displayed on the page. [#user-key-security] === User key security @@ -232,6 +309,48 @@ ERROR: Repository not found. Permission denied (publickey). ``` -== Feature support + +[#create-additional-ssh-keys] +== 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. This 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`. + +. Create an SSH key-pair by following the link:https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/[GitHub instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): ++ +[source,console] +---- +$ 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: ++ +```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. + +For a guide to additional SSH keys for CircleCI pipelines, see the xref:integration:add-ssh-key.adoc[Add SSH keys] page. +== Feature support \ No newline at end of file From dbba56bf64341a35c8fbc6af3029acd1b6175195 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Fri, 24 Oct 2025 13:31:54 +0100 Subject: [PATCH 06/23] more consolidation --- ...-organizations-and-integrations-guide.adoc | 131 +++++++++++++++++- 1 file changed, 127 insertions(+), 4 deletions(-) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 1877391e81..36cf24d1b7 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -75,6 +75,16 @@ The integration options available to you depend on your organization type, as fo |=== +== Quickstart + +The followin links take you to the sections you need to get set up with CircleCI: + +* xref:getting-started:first-steps.adoc[Sign up and create an organization] +* xref:getting-started:invite-your-team.adoc[Join a team or invite your team] +* xref:getting-started:create-project.adoc[Create a project] +* xref:orchestrate:pipelines.adoc[Set up a pipeline] +* xref:orchestrate:set-up-triggers.adoc[Set up a trigger] + == View and manage integrations You can view and manage integrations in two places depending on your organization type. The following sections describe your options for each integration type. @@ -99,6 +109,16 @@ You can _disconnect_ your Bitbucket Cloud integration. Doing so will remove your ##GITLAB BBDC REMOVAL INSTRUCTIONS?# +=== Can I integrate a GitHub org with multiple CircleCI orgs? + +A GitHub org with the CircleCI GitHub App installed can only be integrated with one CircleCI organization. + +In this scenario, attempting to integrate with a second CircleCI organization will redirect you to a GitHub App integration settings page when creating a project. If you are not sure what other CircleCI organization may be connected to your GitHub organization, you can submit a request link:https://forms.gle/dvcXN8ArByXqNNbJ7[here]. + +#Benny can you help with this section?# + +image::guides:ROOT:github-app-configuration-page.png[Create a project] + == Invite your team to your organization #Add instructions for inviting for each org type# @@ -109,7 +129,7 @@ For `github` and `bitbucket` type organizations user permissions are inherited f For `circleci` type organizations user permissions are managed through CircleCI. You can find information on managing organization and project roles and permissions starting with the xref:permissions-authentication:roles-and-permissions-overview.adoc[Roles and Permissions] page. You can manage roles and permissions at an organization and project level. You can manage roles and permissions individually for each user or add users to groups and manage group roles and permissions. -== Projects and pipelines +== Projects For `github` and `bitbucket` type organizations projects are synonymous with repositories. Select "Projects" in the link:https://app.circleci.com/home[CircleCI web app] to view your repositories. From here you have the option to: @@ -129,18 +149,34 @@ For full instructions on renaming organizations and projects, see the xref:secur For full instructions on deleting organizations and projects, see the xref:security:delete-organizations-and-projects.adoc[Delete organizations and repositories] page. +== 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. Each pipeline is defined by a configuration file stored in a repository (typically `.circleci/config.yml`). + +The pipelines you have available to you depend on your organization type and where your code is stored. + +If you have a `circleci` organization: +* If your code is stored in a GitHub repository you can have GitHub App pipelines. +* If your code is stored in a GitLab repository you can have GitLab pipelines. +* If your code is stored in a Bitbucket Data Center repository you can set up Bitbucket Data Center pipelines. + +If you have a `github` organization you can have GitHub App or GitHub OAuth pipelines. + +If you have a `bitbucket` organization you can have Bitbucket Cloud pipelines. + == Triggers The trigger options available to you depend on your pipeline type. These options are described in the following table: -[options="header",cols="1,1,1,1,1,1,1,1"] +[options="header",cols="9*"] |=== |Pipeline type ^|GitHub OAuth trigger -^|Bitbucket CloudOAuth trigger +^|Bitbucket Cloud OAuth trigger ^|GitLab trigger ^|Schedule trigger ^|GitHub App trigger +^|Bitbucket Data Center trigger ^|Custom Webhook ^|API / Manual triggering @@ -151,6 +187,7 @@ The trigger options available to you depend on your pipeline type. These options ^|Zero, one, many ^|[.circle-red]#*No*# ^|[.circle-red]#*No*# +^|[.circle-red]#*No*# ^|[.circle-green]#*Yes*# |GitHub App image:guides:ROOT:icons/github-app.svg[GitHub App pipeline badge, role="no-border"] @@ -159,8 +196,39 @@ The trigger options available to you depend on your pipeline type. These options ^|[.circle-red]#*No*# ^|Zero, one, many ^|Zero, one, many +^|[.circle-red]#*No*# ^|Zero, one, many ^|[.circle-green]#*Yes*# + +|Bitbucket Cloud #insert badge# +^|[.circle-red]#*No*# +^| One +^|[.circle-red]#*No*# +^|Zero, one, many +^|Zero, one, many +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|[.circle-green]#*Yes*# + +|GitLab #insert badge# +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|Zero, one, many +^|Zero, one, many +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|[.circle-green]#*Yes*# + +|Bitbucket Data Center #insert badge# +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|[.circle-red]#*No*# +^|Zero, one, many +^|[.circle-red]#*No*# +^|Zero, one, many +^|[.circle-red]#*No*# +^|[.circle-green]#*Yes*# |=== == How CircleCI checks out your code @@ -352,5 +420,60 @@ When you push to your GitHub repository from a job, CircleCI will use the SSH ke For a guide to additional SSH keys for CircleCI pipelines, see the xref:integration:add-ssh-key.adoc[Add SSH keys] page. +[#Moving-from-github-oauth-app-to-github-app] +== Moving from the GitHub OAuth app integration to the GitHub App integration + +Before attempting to move your information from an org integrated with the GitHub OAuth app to an org integrated with CircleCI’s GitHub App, consider the following: + +* If the motivation for moving is to **leverage new functionality that is only available to the GitHub App integration**, consider using your existing organization and installing the GitHub App alongside your OAuth app integration, as described in xref:guides:integration:using-the-circleci-github-app-in-an-oauth-org.adoc[this guide]. +* If the motivation is to **completely remove the OAuth app integration** for security, compliance, or other reasons, follow the steps below. + +[#Steps-to-migrate-to-an-organization-without-default-GitHub-OAuth-integration] +=== Steps to migrate to an organization without default GitHub OAuth integration -== Feature support \ No newline at end of file +The following steps guide you through migrating you organization as follows: + +* *From* an organization integrated with GitHub through the OAuth integration by default (identifiable by `/github/` or `/gh/` in the URL). +* *To* an organization that does not have a default OAuth integration with GitHub (identifiable by `/circleci/` in the URL). + +[CAUTION] +==== +* You can not currently automate migrating your organization from the GitHub OAuth app to CircleCI's GitHub App integration. +* Before proceeding, confirm that you do not immediately need any of the functionality listed in the <> section below. +* The following steps include *creating a new org*. If you need to transfer private orbs or self-hosted runner resource classes to your new org, contact link:https://support.circleci.com/[Support at CircleCI] before following step 14. +* If you have a dedicated account team at CircleCI, contact them first to discuss your migration. +==== + +. From your existing CircleCI organization in the CircleCI web app, select the organization dropdown in the top-left corner. +. At the bottom of the drop-down, select btn:[Create New Organization]. +. On the "Connect your code" page, select btn:[Connect] next to "GitHub". +. You will be redirected to GitHub to install the CircleCI GitHub App into your GitHub organization. ++ +NOTE: You can install the CircleCI GitHub App into the same GitHub organization that already uses the GitHub OAuth App integration, as long as your original CirlceCI organization is not already connected to it. +. Follow the instructions to create a project that is connected to one of your GitHub repositories. +. If you are on a **paid** pricing plan: +.. Navigate back to the organization that is connected to the GitHub OAuth app +.. Select **Plan** in the CircleCI web app +.. Select the "Share and Transfer" tab +.. Select btn:[Add shared organization] and choose the new organization that you just created that integrates with CircleCI's GitHub App. +. Navigate to the project that was created in step 4 in the "new" organization that is integrated with the GitHub App. Match any custom project settings that you had from your previous project to this new project on the **Project Settings** page. This includes things like environment variables and outbound webhooks. +. Perform a test push of code to your repository to ensure that a pipeline is triggered and is working as expected in your **new** CircleCI organization. +. Assuming the repository you connected is also connected to your previous CircleCI organization, CircleCI will start pipelines when a push event happens to the repository in both the old and new organizations. If your test from step 8 above was successful, go to **Project Settings** in your organization connected to the GitHub OAuth App (your "old" org), scroll down and select btn:[Stop Building]. This will ensure that push events to your repository only trigger pipelines in the project connected to your GitHub App organization. +. Repeat steps 6-9 by selecting menu:Projects[Create a Project] for each project that you had set up in your previous organization. +. If you are using xref:security:contexts.adoc[contexts], you will need to recreate the contexts in your new organization. +. Invite your teammates to the new organization (the one that is integrated with the CircleCI GitHub App) using the instructions on xref:getting-started:invite-your-team.adoc[this page]. +. If you are on a **paid** pricing plan and followed step 6: +.. Navigate back to the "old" organization and select menu:Plan[Share and Transfer]. +.. Select the image:guides:ROOT:icons/cancel.svg[delete icon, role="no-border"] next to the "new" organization to remove the shared relationship between the "new" and "old" organizations. +.. Select btn:[Transfer Plan] and follow the instructions to transfer the plan from the "old" organization to the "new" organization. +. At this point, you will be left with a GitHub App-integrated organization that has the same payment plan and projects as your previous organization. If you get logged out, you can continue to use the "Login with GitHub" button on link:https://circleci.com/login[the CircleCI login page] as long as the old organization is not deleted. + +NOTE: Data from xref:insights:insights.adoc[Insights] and historical pipeline runs will not be present in your new organization. Contexts will not be present until you recreate them for your new org. + +== 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 xref:reference:ROOT:variables.adoc[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 xref:integration:version-control-system-integration-overview.adoc[Version Control System Integration Overview] page. \ No newline at end of file From 2b03cc7fbe17ac48bc123285c978b1df24c114d4 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Wed, 5 Nov 2025 11:32:55 +0000 Subject: [PATCH 07/23] bring across some more integraiton content and add user settings --- ...-organizations-and-integrations-guide.adoc | 205 ++++++++++++++++-- 1 file changed, 187 insertions(+), 18 deletions(-) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 36cf24d1b7..b2a095d2ad 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -3,35 +3,67 @@ :page-description: A guide to understanding user accounts, organizations and integrations with version control systems in CircleCI. :experimental: -This guide defines the concepts of user, organization and integration in CircleCI. After these concepts are covered you will find out about the features available to you depending on you organization and pipeline type. +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 account When you log in to CircleCI you are logging in to your _user account_. -#user settings# +As a CircleCI _user_ you can access _organizations_. You can access zero, one or many organizations. You can create new organizations and/or join an existing organization. -As a CircleCI _user_ you can access _organizations_. You can have access to zero, one or many organizations. - -There are two ways to log in to CircleCI: +You can log in to CircleCI using one of the following methods: * Email and password * Social login (GitHub, Bitbucket) -#INSTRUCTION FOR DELETING A USERT ACCOUNT?# +Select your icon in the top bar and select **User settings** to access the following sections: + +.User settings +[cols="1,2", options="header"] +|=== +| User settings section | What you will find here + +| Account Integrations +| Displays your user ID as well as account integrations with VCS providers. You will find a list of which GitHub or Bitbucket organizations you are connected with. You can disconnect your OAuth connections with GitHub or Bitbucket here. + +| Notifications +| Set your individual email and web notification preferences. This includes preferences around builds, branches, and project notifications. Web notifications will appear in your browser. + +| Accessibility +| Toggle switch for accessible step output. Switch this on if you use a screen reader. + +| Privacy & Security +| Disable third-party tracking. You may opt in or opt out of third party tracking pixels. + +| Sessions +| A list of systems that have logged into your account. Revoke any sessions that you do not recognize. + +| Personal API tokens +| View and create personal API tokens, used to access the CircleCI API. + +| Organization Plans +| See the list of organizations you are a part of. If you have administrative privileges, you may also view the plan each organization is on. + +| Job SSH keys +| Set up an SSH key to access your job containers. For more information on this feature see the xref:execution-managed:ssh-access-jobs.adoc[Debug with SSH] page. + +| Beta Program +| Opt in to CircleCI's beta program. Beta features you opt in to will be listed on this page. + +|=== == Organizations An organization in CircleCI is a workspace that serves as a container for your team's projects, settings, permissions, and billing. Organizations are typically linked to your version control system (VCS) account(s) (GitHub, GitLab, or Bitbucket). -Create an organization allows you to manage the following: +Create an organization to manage the following: * Multiple projects under a single entity. * CI/CD pipelines specific to your team or company needs. * Invites for team members. -* Assignment of roles (`circleci` orgs only, roles for `github` and `bitbucket` orgs are managed through the VCS provider). +* Assignment of roles (`circleci` orgs only, roles for `github` and `bitbucket` orgs are inherited and managed through the VCS provider). -Each organization has its own settings, including security, integrations, and resource management, making it easier to coordinate and control your CI/CD processes across multiple projects and users. +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. A CircleCI _organization_ can be one of three types: @@ -75,9 +107,71 @@ The integration options available to you depend on your organization type, as fo |=== +== Disconnect a GitHub OAuth or Bitbucket Cloud account from your user 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/Bitbucket user account +* Changes to the organization name in your VCS +**** + +. From the link:https://app.circleci.com/[CircleCI web app], navigate to your **User Settings** by clicking on your user icon in the top bar. +. Select **Account Integrations**. +. You will see a list of connections along with the GitHub or Bitbucket organizations they are associated with. Select btn:[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. + +== Projects + +[tabs] +==== +`github` and `bitbucket` organizations:: ++ +-- +For `github` and `bitbucket` type organizations projects are synonymous with repositories. Select "Projects" in the link:https://app.circleci.com/home[CircleCI web app] to view your repositories. From here you have the option to: + +* Set up new repositories as CircleCI projects, which involves committing a CircleCI `config.yml` file to the repository to define your pipeline. THis creates a GitHub OAuth or Bitbucket Cloud pipeline for you, which you can view in menu:Project Settings[Project Setup] or menu:Project Settings[Pipelines] . +* 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 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 link:https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807[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 link:https://developer.github.com/v3/repos/hooks/#edit-a-hook[GitHub Edit a Hook document] for details. + +Refer to the CircleCI documentation on xref:orchestrate:workflows.adoc#using-filters-in-your-workflows[Workflow filters] for information on how to build tag pushes. +-- +`circleci` organizations:: ++ +-- +For `circleci` type organizations, projects are created directly in CircleCI via the web app, API or CLI. Select "Projects" in the link:https://app.circleci.com/home[CircleCI web app] to view your projects. From here you have the option to: + +* Create a new project, including setting up a pipeline, at which point you connect your code repository to your project. +* Follow/unfollow projects, to subscribe/unsubscribe from notifications for builds. +-- +==== + == Quickstart -The followin links take you to the sections you need to get set up with CircleCI: +The following links take you to the sections you need to get set up with CircleCI: * xref:getting-started:first-steps.adoc[Sign up and create an organization] * xref:getting-started:invite-your-team.adoc[Join a team or invite your team] @@ -129,17 +223,65 @@ For `github` and `bitbucket` type organizations user permissions are inherited f For `circleci` type organizations user permissions are managed through CircleCI. You can find information on managing organization and project roles and permissions starting with the xref:permissions-authentication:roles-and-permissions-overview.adoc[Roles and Permissions] page. You can manage roles and permissions at an organization and project level. You can manage roles and permissions individually for each user or add users to groups and manage group roles and permissions. -== Projects +=== OAuth permissions -For `github` and `bitbucket` type organizations projects are synonymous with repositories. Select "Projects" in the link:https://app.circleci.com/home[CircleCI web app] to view your repositories. From here you have the option to: +[tabs] +==== +GitHub OAuth:: ++ +-- +CircleCI requests the following permissions from GitHub, defined in the link:https://developer.github.com/v3/oauth/#scopes[GitHub permissions model]. -* Set up new repositories as CircleCI projects, which involves committing a CircleCI `config.yml` file to the repository to define your pipeline. THis creates a GitHub OAuth or Bitbucket Cloud pipeline for you, which you can view in menu:Project Settings[Project Setup] or menu:Project Settings[Pipelines] . -* Follow/unfollow projects, to subscribe/unsubscribe from notifications for builds. +**Read Permission** -For `circleci` type organizations, projects are created separately to code repositories directly in CIrcleCI via the web app, API or CLI. Select "Projects" in the link:https://app.circleci.com/home[CircleCI web app] to view your projects. From here you have the option to: +- 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 + +NOTE: 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 link:https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/#available-scopes[`repo` scope], which is write-level access. GitHub does not provide a read-only OAuth scope for listing all of a user’s repositories. +-- +Bitbucket Cloud OAuth:: ++ +-- +CircleCI requests the following permissions from Bitbucket Cloud, as defined in the link:https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html#OAuthonBitbucketCloud-Scopes[Bitbucket Cloud 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 + +NOTE: CircleCI only asks for permissions that are absolutely necessary. However, CircleCI is constrained by the specific permissions Bitbucket Cloud chooses to supply. + +If you feel strongly about reducing the number of permissions CircleCI uses, consider contacting Bitbucket to communicate your concerns. +-- +==== + +=== GitHub OAuth 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 menu:Organization Settings[VCS > GitHub Checks] +* GitHub status updates, from the CircleCI web app menu:Project Settings[Advanced > GitHub Status Updates] + +For more information on GitHub Checks and GitHub status updates, see the xref:integration:enable-checks.adoc#github-check-and-github-status-updates[Enabling GitHub Checks]. -* Create a new project, including setting up a pipeline, at which point you connect your code repository to your project. -* Follow/unfollow projects, to subscribe/unsubscribe from notifications for builds. == Rename an organization or project @@ -420,6 +562,10 @@ When you push to your GitHub repository from a job, CircleCI will use the SSH ke For a guide to additional SSH keys for CircleCI pipelines, see the xref:integration:add-ssh-key.adoc[Add SSH keys] page. +== Built-in environment variables and pipeline values + +The built-in environment variables available in a project depend on the pipeline type. For a full list see the xref:reference:ROOT:variables.adoc[Project values and variables] page. + [#Moving-from-github-oauth-app-to-github-app] == Moving from the GitHub OAuth app integration to the GitHub App integration @@ -476,4 +622,27 @@ The built-in environment variables and pipeline values available to you depend o == Feature support -Some organization and project combinations affect the features that are available to you. For a full list, see the xref:integration:version-control-system-integration-overview.adoc[Version Control System Integration Overview] page. \ No newline at end of file +Some organization and project combinations affect the features that are available to you. For a full list, see the xref:integration:version-control-system-integration-overview.adoc[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 link:https://help.github.com/articles/about-third-party-application-restrictions/[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 were 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 link:https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/enabling-oauth-app-access-restrictions-for-your-organization[GitHub docs] + +NOTE: 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. + +== Frequently asked questions + +=== How do I delete my user account? + +For guidance on deleting your user account link:https://support.circleci.com/hc/en-us/articles/360037058873-How-Do-I-Delete-My-User-Account#h_01JMMX9C1BAM445WCFZF56QMEE[see this support article]. \ No newline at end of file From ca795f4b576bd96230fb4852041e9ab5ddbcc052 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Thu, 6 Nov 2025 12:27:43 +0000 Subject: [PATCH 08/23] update links to integration page and archive github and bitbucket integration pages --- .../bitbucket-integration.adoc | 0 .../github-apps-integration.adoc | 1 + .../pages => archive}/github-integration.adoc | 4 +- docs/guides/modules/ROOT/nav.adoc | 3 - .../ROOT/partials/faq/pipelines-faq-snip.adoc | 2 +- .../ROOT/partials/tips/check-org-type.adoc | 10 + .../about-circleci/pages/concepts.adoc | 10 +- .../introduction-to-the-circleci-web-app.adoc | 4 +- .../deploy/pages/set-up-rollbacks.adoc | 2 +- .../set-up-the-circleci-release-agent.adoc | 4 +- .../getting-started/pages/create-project.adoc | 4 +- .../getting-started/pages/first-steps.adoc | 8 +- .../pages/invite-your-team.adoc | 8 +- .../integration/pages/add-ssh-key.adoc | 13 +- .../pages/github-trigger-event-options.adoc | 2 +- .../pages/how-to-override-config.adoc | 4 +- ...ple-configuration-files-for-a-project.adoc | 2 +- .../pages/manage-groups.adoc | 4 +- .../pages/manage-roles-and-permissions.adoc | 4 +- .../pages/roles-and-permissions-overview.adoc | 4 +- ...-organizations-and-integrations-guide.adoc | 263 ++++++++++++++---- ...rename-organizations-and-repositories.adoc | 2 +- .../pages/rotate-project-ssh-keys.adoc | 18 +- .../test/pages/test-splitting-tutorial.adoc | 10 +- ...et-started-with-the-vs-code-extension.adoc | 4 +- .../pages/vs-code-extension-overview.adoc | 4 +- .../modules/author/pages/create-an-orb.adoc | 2 +- .../modules/ROOT/pages/glossary.adoc | 6 +- .../pages/outbound-webhooks-reference.adoc | 6 +- .../modules/ROOT/pages/variables.adoc | 2 +- 30 files changed, 284 insertions(+), 126 deletions(-) rename {docs/guides/modules/integration/pages => archive}/bitbucket-integration.adoc (100%) rename {docs/guides/modules/integration/pages => archive}/github-apps-integration.adoc (99%) rename {docs/guides/modules/integration/pages => archive}/github-integration.adoc (97%) create mode 100644 docs/guides/modules/ROOT/partials/tips/check-org-type.adoc diff --git a/docs/guides/modules/integration/pages/bitbucket-integration.adoc b/archive/bitbucket-integration.adoc similarity index 100% rename from docs/guides/modules/integration/pages/bitbucket-integration.adoc rename to archive/bitbucket-integration.adoc diff --git a/docs/guides/modules/integration/pages/github-apps-integration.adoc b/archive/github-apps-integration.adoc similarity index 99% rename from docs/guides/modules/integration/pages/github-apps-integration.adoc rename to archive/github-apps-integration.adoc index d57b533b49..9e4ffa62c3 100644 --- a/docs/guides/modules/integration/pages/github-apps-integration.adoc +++ b/archive/github-apps-integration.adoc @@ -2,6 +2,7 @@ :page-platform: Cloud :page-description: Learn how to integrate CircleCI with GitHub using GitHub Apps. :experimental: +:page-alias: guides:integration:github-apps-integration.adoc If your CircleCI organization is integrated with GitHub through the **CircleCI GitHub App**, the content on this page is for you. diff --git a/docs/guides/modules/integration/pages/github-integration.adoc b/archive/github-integration.adoc similarity index 97% rename from docs/guides/modules/integration/pages/github-integration.adoc rename to archive/github-integration.adoc index 6f9c83ec32..17e8c066fd 100644 --- a/docs/guides/modules/integration/pages/github-integration.adoc +++ b/archive/github-integration.adoc @@ -234,7 +234,7 @@ Provide CircleCI with a GitHub user key in your project's **Project Settings** > [#establish-the-authenticity-of-an-ssh-host] == 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 GitHub to a "known hosts" file (`~/.ssh/known_hosts`). Using `known_hosts` allows the executor can verify that the host it is connecting to is authentic. The xref:reference:ROOT:configuration-reference.adoc#checkout[`checkout` job step] does this automatically, so you will need to run the following commands if you opt to use a custom checkout command: +When using SSH keys to check out a repository, it may be necessary to add the fingerprints for GitHub 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. The xref:reference:ROOT:configuration-reference.adoc#checkout[`checkout` job step] does this automatically, so you will need to run the following commands if you opt to use a custom checkout command: ```shell mkdir -p ~/.ssh @@ -331,7 +331,7 @@ If you would like to rename your organization or repository, follow the xref:sec [#using-github-app-functionality] == Using GitHub App functionality alongside the GitHub OAuth App -Some existing and future functionality on CircleCI can only be enabled through the more secure xref:github-apps-integration.adoc[CircleCI GitHub App integration]. +Some existing and future functionality on CircleCI can only be enabled through the more secure CircleCI GitHub App integration. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide] for more information. Until October 2024, the CircleCI GitHub App integration was available exclusively to organizations created after September 2023. **Now, all organizations can install the CircleCI GitHub App to access new functionality. This includes organizations that currently integrate with CircleCI GitHub OAuth app.** diff --git a/docs/guides/modules/ROOT/nav.adoc b/docs/guides/modules/ROOT/nav.adoc index 8761508936..ed46cabefc 100644 --- a/docs/guides/modules/ROOT/nav.adoc +++ b/docs/guides/modules/ROOT/nav.adoc @@ -271,12 +271,9 @@ *** xref:integration:notifications.adoc[Notifications] ** VCS integration *** xref:integration:version-control-system-integration-overview.adoc[VCS integration overview] -*** xref:integration:github-apps-integration.adoc[GitHub App integration] -*** xref:integration:github-integration.adoc[GitHub OAuth app integration] *** xref:guides:integration:using-the-circleci-github-app-in-an-oauth-org.adoc[Using the CircleCI GitHub App in an OAuth org] *** xref:integration:gitlab-integration.adoc[GitLab integration] *** xref:integration:bitbucket-data-center-integration.adoc[Bitbucket data center integration] -*** xref:integration:bitbucket-integration.adoc[Bitbucket Cloud integration] *** xref:integration:oss.adoc[Build open source projects] ** Third-party integrations diff --git a/docs/guides/modules/ROOT/partials/faq/pipelines-faq-snip.adoc b/docs/guides/modules/ROOT/partials/faq/pipelines-faq-snip.adoc index fa8646fe01..debcd3f1e4 100644 --- a/docs/guides/modules/ROOT/partials/faq/pipelines-faq-snip.adoc +++ b/docs/guides/modules/ROOT/partials/faq/pipelines-faq-snip.adoc @@ -12,6 +12,6 @@ While splitting configuration files is only available for GitHub App integration [#build-forked-prs-using-pipelines] === Can I trigger forked PRs using pipelines? -NOTE: The "build forked PRs" settings is not currently supported for GitLab or GitHub App projects. To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the xref:guides:integration:github-apps-integration.adoc[GitHub App integration] page. +NOTE: The "build forked PRs" settings is not currently supported for GitLab or GitHub App pipelines. Check menu:Project Settings[Project setup] or menu:Project Settings[Pipelines] to see your pipeline type. You can trigger pipelines to build PRs from forked repositories with CircleCI link:https://circleci.com/docs/api/v2/[API v2]. However, by default, CircleCI will not build a PR from a forked repository. If you would like to turn this feature on, navigate to menu:Project Settings[Advanced] in the web app. If you would like more information, you can view this link:https://support.circleci.com/hc/en-us/articles/360049841151-Trigger-pipelines-on-forked-pull-requests-with-CircleCI-API-v2[support article]. diff --git a/docs/guides/modules/ROOT/partials/tips/check-org-type.adoc b/docs/guides/modules/ROOT/partials/tips/check-org-type.adoc new file mode 100644 index 0000000000..b675e0272e --- /dev/null +++ b/docs/guides/modules/ROOT/partials/tips/check-org-type.adoc @@ -0,0 +1,10 @@ +**** +To check your organization type, check your organization slug at menu:Organization settings[Overview]. `github` and `bitbucket` type organizations are OAuth authenticated orgs and the organization slug is structured as follows: + +* `github/` or `gh/` +* `bitbucket/` or `bb/` + +An organization slug for a `circleci` type organization is in the following format: + +* `circleci/` +**** \ No newline at end of file diff --git a/docs/guides/modules/about-circleci/pages/concepts.adoc b/docs/guides/modules/about-circleci/pages/concepts.adoc index 91c6df420d..e0ce88a7ae 100644 --- a/docs/guides/modules/about-circleci/pages/concepts.adoc +++ b/docs/guides/modules/about-circleci/pages/concepts.adoc @@ -455,9 +455,9 @@ See the xref:orchestrate:pipelines.adoc[Pipelines overview] page for more inform [#projects] == Projects -For xref:integration:github-integration.adoc[GitHub OAuth app] and xref:integration:bitbucket-integration.adoc[Bitbucket Cloud] accounts, a _project_ in CircleCI is tied to, and shares the name of the associated code repository in your VCS. +For GitHub OAuth app and Bitbucket Cloud accounts, a _project_ in CircleCI is tied to, and shares the name of the associated code repository in your VCS. -For xref:integration:github-apps-integration.adoc[GitHub App], xref:integration:gitlab-integration.adoc[GitLab SaaS and self-managed] and xref:integration:bitbucket-data-center-integration.adoc[Bitbucket Data Center] users, a _project_ in CircleCI is standalone. You name your project and then connect your code (in your GitHub, GitLab or Bitbucket Data Center repository) to that project. +For GitHub App, GitLab SaaS and self-managed and Bitbucket Data Center users, a _project_ in CircleCI is standalone. You name your project and then connect your code (in your GitHub, GitLab or Bitbucket Data Center repository) to that project. **** **Project names** must meet the following requirements: @@ -541,12 +541,12 @@ See the xref:orchestrate:jobs-steps.adoc[Jobs and steps] page for more informati [#user-types] == User roles -CircleCI roles are set up differently depending on how you xref:integration:version-control-system-integration-overview.adoc[integrate your code]. +CircleCI roles are set up differently depending on your xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organization-type[organization type]. -TIP: To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the xref:integration:github-apps-integration.adoc[GitHub App integration] page. +include::ROOT:partial$tips/check-org-type.adoc[] === GitHub App, GitLab and Bitbucket Data Center users -Roles are set at the organization and project level and are separate to permissions and roles set in the version control system in which your code is stored. The available roles are: +For `circleci` type organizations, roles are set at the organization and project level and are separate to permissions and roles set in the version control system in which your code is stored. The available roles are: * Admin * Contributor diff --git a/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc b/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc index 1171b35b10..eeca3d360d 100644 --- a/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc +++ b/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc @@ -17,7 +17,9 @@ Inside the application, you will find the features including the following: This page is not an exhaustive guide to the web app, but is an introduction to some of the information, options, and settings available. -NOTE: Some settings and functionality described in on this page, including the in-app configuration editor, are currently not available for xref:integration:github-apps-integration.adoc[GitHub App], xref:integration:gitlab-integration.adoc[GitLab] and xref:integration:bitbucket-data-center-integration.adoc[Bitbucket Data Center] projects. For an overview of feature availability for each integration type, see the xref:integration:version-control-system-integration-overview.adoc[VCS integration overview] page. +Some settings and functionality described in on this page, including the in-app configuration editor, are currently not available for `circleci` type organizations. For an overview of feature availability for each organization/integration type, see the xref:integration:version-control-system-integration-overview.adoc[VCS integration overview] page. + +include::ROOT:partial$tips/check-org-type.adoc[] == User homepage diff --git a/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc b/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc index bce2d96200..89ccacde5a 100644 --- a/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc +++ b/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc @@ -56,7 +56,7 @@ image::guides:ROOT:deploy/project-overview-rollback.png[Rollback button on proje === 2. Confirm GitHub App installation -NOTE: To set up rollback pipelines, you must connect your organization to the xref:integration:github-apps-integration.adoc[CircleCI GitHub App]. +NOTE: To set up rollback pipelines, you must install the CircleCI GitHub App into your organization. For more information, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#install-the-circleci-github-app[Users, organizations, and integrations guide]. - If the GitHub App is not installed in your organization, the guided setup process prompts you to install it. + diff --git a/docs/guides/modules/deploy/pages/set-up-the-circleci-release-agent.adoc b/docs/guides/modules/deploy/pages/set-up-the-circleci-release-agent.adoc index 20bd7e7216..3f40552688 100644 --- a/docs/guides/modules/deploy/pages/set-up-the-circleci-release-agent.adoc +++ b/docs/guides/modules/deploy/pages/set-up-the-circleci-release-agent.adoc @@ -27,7 +27,9 @@ Before setting up your environment integration with CircleCI, run through the fo * A CircleCI account connected to your code. You can link:https://circleci.com/signup/[sign up for free]. * A Kubernetes cluster. * A project building on CircleCI that deploys to your Kubernetes cluster. See the xref:getting-started:create-project.adoc[Create a project] page for steps. -* You must have write access to the project associated with the component being deployed. For full details of roles and permissions for GitLab and GitHub App integrations, see the xref:permissions-authentication:roles-and-permissions-overview.adoc[Roles and permissions overview]. If your integration is through Bitbucket or the GitHub OAuth app, you will need to be an org admin in Bitbucket/GitHub respectively. To find out which GitHub integration you have, see the xref:integration:github-apps-integration.adoc[GitHub App integration] page. +* You must have write access to the project associated with the component being deployed. For full details of roles and permissions for `circleci` type organizations see the xref:permissions-authentication:roles-and-permissions-overview.adoc[Roles and permissions overview]. If you have a `github` or `bitbucket` type organization, you will need to be an org admin in Bitbucket/GitHub respectively. + +include::ROOT:partial$tips/check-org-type.adoc[] The following versions of Kubernetes, Helm, and Argo Rollouts have been tested and proven to work. Older versions may work but are not guaranteed: diff --git a/docs/guides/modules/getting-started/pages/create-project.adoc b/docs/guides/modules/getting-started/pages/create-project.adoc index c78c651dfa..71556a4065 100644 --- a/docs/guides/modules/getting-started/pages/create-project.adoc +++ b/docs/guides/modules/getting-started/pages/create-project.adoc @@ -25,7 +25,9 @@ NOTE: Using CircleCI server? Use the <> steps below. Rather th [#create-a-project] === Create a project -NOTE: If you have integrated your code with the xref:integration:github-apps-integration.adoc[CircleCI GitHub App], xref:integration:gitlab-integration.adoc[GitLab], or xref:integration:bitbucket-data-center-integration.adoc[Bitbucket Data Center], the steps in this section apply to you. +If you are using a `circleci` type organization, the steps in this section apply to you. + +include::ROOT:partial$tips/check-org-type.adoc[] Choose steps to follow below, depending on where your code is stored: diff --git a/docs/guides/modules/getting-started/pages/first-steps.adoc b/docs/guides/modules/getting-started/pages/first-steps.adoc index 2ed5568716..11fe60dadb 100644 --- a/docs/guides/modules/getting-started/pages/first-steps.adoc +++ b/docs/guides/modules/getting-started/pages/first-steps.adoc @@ -76,13 +76,7 @@ If you are signing up using an invite from your team, you will be _joining_ an e NOTE: If you are setting up a project for the first time, you may need to authenticate with your VCS provider. Once you have completed a one-time authentication, you will be able to set up subsequent projects in CircleCI more quickly. Refer to the xref:create-project.adoc[Creating a Project] guide for more information. -Guides for integrating GitHub, Bitbucket, or GitLab projects are available as follows: - -- xref:integration:github-apps-integration.adoc[GitHub App integration] -- xref:integration:github-integration.adoc[GitHub OAuth app integration] -- xref:integration:bitbucket-integration.adoc[Bitbucket Cloud integration] -- xref:integration:gitlab-integration.adoc[GitLab integration] -- xref:integration:bitbucket-data-center-integration.adoc[Bitbucket Data Center integration] +For a guide to integrating your code with CircleCI, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide]. [#terms] == Terms diff --git a/docs/guides/modules/getting-started/pages/invite-your-team.adoc b/docs/guides/modules/getting-started/pages/invite-your-team.adoc index 20602909a9..54750bcc89 100644 --- a/docs/guides/modules/getting-started/pages/invite-your-team.adoc +++ b/docs/guides/modules/getting-started/pages/invite-your-team.adoc @@ -53,11 +53,13 @@ NOTE: If you do not see the organization you would like to join listed, you will The steps in this section show how an org admin can invite teammates to join their organization. -include::ROOT:partial$tips/check-github-type-org.adoc[] +The steps are different depending on your organization type. + +include::ROOT:partial$tips/check-org-type.adoc[] [tabs] ==== -GitHub App GitLab Bitbucket Data Center:: +`circleci` type organization:: + -- . In the CircleCI web app, select your org from the org cards on your user homepage. @@ -67,7 +69,7 @@ GitHub App GitLab Bitbucket Data Center:: image::guides:ROOT:invite-teammates-standalone.png[Navigate to Organization Settings, People, use the Invite form] -- -GitHub OAuth Bitbucket Cloud:: +`github` or `bitbucket` type organization:: + -- . In the CircleCI web app, select your org from the org cards on your user homepage. diff --git a/docs/guides/modules/integration/pages/add-ssh-key.adoc b/docs/guides/modules/integration/pages/add-ssh-key.adoc index af2f554b93..c05dfb6d94 100644 --- a/docs/guides/modules/integration/pages/add-ssh-key.adoc +++ b/docs/guides/modules/integration/pages/add-ssh-key.adoc @@ -3,7 +3,7 @@ :page-description: How to add additional SSH keys to CircleCI :experimental: -Add additional SSH keys to your project for access to deploy other services or to write to, or checkout code from other repositories. +Add additional SSH keys to your project for access to deploy to other services or to write to, or checkout code from other repositories. If you want to set up an SSH key in order to checkout code from additional repositories in GitHub (xref:github-integration.adoc[GitHub OAuth app only]) or Bitbucket Cloud within a job, refer to the xref:github-integration.adoc#enable-your-project-to-check-out-additional-private-repositories[GitHub OAuth app] or xref:bitbucket-integration.adoc#enable-your-project-to-check-out-additional-private-repositories[Bitbucket Cloud] integration pages. If you need additional SSH keys to access other services and your org is set up to the use xref:github-integration.adoc[GitHub OAuth app] or Bitbucket Cloud, follow the steps below. @@ -105,13 +105,4 @@ Example: [source,bash] ---- ssh -i ~/.ssh/id_rsa_a3f982c51d479be68832a1bcf4297e15 -o "IdentitiesOnly=yes" user@hostname ----- - -[#see-also] -== See also - -* xref:github-integration.adoc[GitHub OAuth app integration] -* xref:github-apps-integration.adoc[GitHub App integration] -* xref:bitbucket-integration.adoc[Bitbucket integration] -* xref:bitbucket-data-center-integration.adoc[Bitbucket Data Center integration] -* xref:gitlab-integration.adoc[GitLab integration] +---- \ No newline at end of file diff --git a/docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc b/docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc index fd3d3c04af..845f8a6867 100644 --- a/docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc +++ b/docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc @@ -129,7 +129,7 @@ Config orchestration tools are available from within your pipelines are as follo === Prerequisites * A CircleCI account. You can sign up for free at link:https://circleci.com/signup/[circleci.com]. -* Your CircleCI account must be linked to a GitHub account, either via xref:integration:github-integration.adoc[GitHub OAuth] or via the xref:integration:github-apps-integration.adoc[CircleCI GitHub App]. +* Your CircleCI account must be linked to a GitHub account, either via GitHub OAuth or via the CircleCI GitHub App. * A GitHub App pipeline that you want to trigger when a PR is opened. You can find steps on the xref:pipelines.adoc#add-or-edit-a-pipeline[Pipelines overview and setup] page. === Steps diff --git a/docs/guides/modules/orchestrate/pages/how-to-override-config.adoc b/docs/guides/modules/orchestrate/pages/how-to-override-config.adoc index e97168b951..21d46c0de9 100644 --- a/docs/guides/modules/orchestrate/pages/how-to-override-config.adoc +++ b/docs/guides/modules/orchestrate/pages/how-to-override-config.adoc @@ -30,7 +30,7 @@ Before following this how-to guide, ensure you have met the following prerequisi * A CircleCI account, xref:getting-started:first-steps.adoc#[you can sign up for free]. * Familiarity with CircleCI configuration files. See the xref:getting-started:introduction-to-yaml-configurations.adoc[Introduction to YAML Configurations] guide for more information. * Familiarity with the concepts of URL and registry orbs, and the URL orb allow-list. See the xref:orbs:use:orb-intro.adoc[Orbs intro] and the xref:orbs:use:managing-url-orbs-allow-lists.adoc[Managing URL orb allow-lists] guide for more information. -* xref:integration:github-apps-integration.adoc[GitHub App integration]. This is optional but recommended to get the best experience with centralized configs due to the ability to define pipelines in which the configuration files is stored outside the project repository. +* A GitHub App integration. This is optional but recommended to get the best experience with centralized configs due to the ability to define pipelines in which the configuration files is stored outside the project repository. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide] for more information. == Simple config override example @@ -273,7 +273,7 @@ This allows importing configurations from any repository in your GitHub organiza === 4. Set up pipeline definitions For each project using the centralized configuration the platform team needs to: -* Configure the project to use GitHub App integration. The CircleCI GitHub App integration is required to use a config source outside the project repo. See the xref:integration:github-apps-integration#[GitHub App integration] guide for more information. +* Ensure the organization has the CircleCI GitHub App installed. The CircleCI GitHub App integration is required to use a config source outside the project repo. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide] for more information. * Create a pipeline definition pointing to the central template configuration. This means setting up a pipeline in which the config source is outside the project repository. The config source will be the centralized, _template_ configuration managed by the platform team. [#transitioning-to-centralized-configs] diff --git a/docs/guides/modules/orchestrate/pages/set-up-multiple-configuration-files-for-a-project.adoc b/docs/guides/modules/orchestrate/pages/set-up-multiple-configuration-files-for-a-project.adoc index 641c5b9340..fc88898662 100644 --- a/docs/guides/modules/orchestrate/pages/set-up-multiple-configuration-files-for-a-project.adoc +++ b/docs/guides/modules/orchestrate/pages/set-up-multiple-configuration-files-for-a-project.adoc @@ -24,7 +24,7 @@ For a full list, see the xref:github-trigger-event-options.adoc[GitHub trigger e To use multiple pipelines and configs for a project in CircleCI, you will need to meet the following prerequisites: -* A CircleCI account connected to your code in GitHub. You can link:https://circleci.com/signup/[sign up for free]. Any of CircleCI's GitHub integrations are supported, read our link:https://discuss.circleci.com/t/product-update-using-github-app-functionality-in-a-github-oauth-app-organization/52204/1[community forum] for background on how this functionality can be used with an org integrated CircleCI's GitHub OAuth App. To use multiple pipelines for a project you will use the xref:integration:github-apps-integration.adoc[CircleCI GitHub App integration]. +* A CircleCI account connected to your code in GitHub. You can link:https://circleci.com/signup/[sign up for free]. Using GitHub you can integrate your code through the CircleCI GitHub App or the GitHub OAuth app. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide] for more information. * A project set up in CircleCI that you want to configure with multiple, distinct pipelines defined with different configuration files. See the xref:getting-started:create-project.adoc[Create a project in CircleCI] page for steps to get your project set up in CircleCI. [#add-additional-config-file] diff --git a/docs/guides/modules/permissions-authentication/pages/manage-groups.adoc b/docs/guides/modules/permissions-authentication/pages/manage-groups.adoc index 42014cc2e1..b7d0336805 100644 --- a/docs/guides/modules/permissions-authentication/pages/manage-groups.adoc +++ b/docs/guides/modules/permissions-authentication/pages/manage-groups.adoc @@ -3,7 +3,9 @@ :page-description: How-to guides for setting up and assigning groups in CircleCI to manage roles and permissions across projects. :experimental: -NOTE: If you authenticated your CircleCI account with xref:integration:gitlab-integration.adoc[GitLab] or the CircleCI xref:integration:github-apps-integration.adoc[GitHub App], the content on this page applies to you. +If you have a `circleci` type organization, the content on this page applies to you. + +include::ROOT:partial$tips/check-org-type.adoc[] Use groups to manage access to projects and features. By creating groups based on teams or roles within your organization, you can, for example, add a user to a group to give them access to all required projects (for example, mobile projects, DevOps projects). For more information about the roles available, and their associated permissions, see the xref:roles-and-permissions-overview.adoc[Roles and permissions] overview page. diff --git a/docs/guides/modules/permissions-authentication/pages/manage-roles-and-permissions.adoc b/docs/guides/modules/permissions-authentication/pages/manage-roles-and-permissions.adoc index a46d648ea8..c234387dc1 100644 --- a/docs/guides/modules/permissions-authentication/pages/manage-roles-and-permissions.adoc +++ b/docs/guides/modules/permissions-authentication/pages/manage-roles-and-permissions.adoc @@ -3,7 +3,9 @@ :page-description: How-to guides for managing roles and permissions in CircleCI. :experimental: -NOTE: If you authenticated your CircleCI account with xref:integration:gitlab-integration.adoc[GitLab] or the CircleCI xref:integration:github-apps-integration.adoc[GitHub App], the content on this page applies to you. +If you have a `circleci` type organization, the content on this page applies to you. + +include::ROOT:partial$tips/check-org-type.adoc[] Manage user access to organizations and projects with CircleCI roles and associated permissions. The guides on this page show how to add people to your organization, update permissions, and assign specific project roles to people in your organization. You can also manage roles for groups of users with xref:manage-groups.adoc[groups].For an overview of roles and permissions in CircleCI, see the xref:roles-and-permissions-overview.adoc[Roles and permissions overview] page. diff --git a/docs/guides/modules/permissions-authentication/pages/roles-and-permissions-overview.adoc b/docs/guides/modules/permissions-authentication/pages/roles-and-permissions-overview.adoc index e4889397f1..2d68b8237e 100644 --- a/docs/guides/modules/permissions-authentication/pages/roles-and-permissions-overview.adoc +++ b/docs/guides/modules/permissions-authentication/pages/roles-and-permissions-overview.adoc @@ -3,7 +3,9 @@ :page-description: An overview of the various project and orgnization roles in CircleCI and the permissions associated with each role. :experimental: -NOTE: If you authenticated your CircleCI account with xref:integration:gitlab-integration.adoc[GitLab] or the CircleCI xref:integration:github-apps-integration.adoc[GitHub App], the content on this page applies to you. +If you have a `circleci` type organization, the content on this page applies to you. + +include::ROOT:partial$tips/check-org-type.adoc[] Manage user access to organizations and projects with CircleCI roles and associated permissions. By default, users can access projects based on roles set at an organization level. For more granular control, you can assign roles at the project level. Manage roles for groups of users with xref:manage-groups.adoc[groups]. diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index b2a095d2ad..816f095e93 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -2,10 +2,11 @@ :page-platform: Cloud :page-description: A guide to understanding user accounts, organizations and integrations with version control systems in CircleCI. :experimental: +:page-aliases: guides:integration:github-apps-integration.adoc, guides:integration:github-integration.adoc, guides:integration:bitbucket-integration.adoc 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 account +== User accounts When you log in to CircleCI you are logging in to your _user account_. @@ -68,62 +69,12 @@ Each organization has its own settings, including security, integrations, and re A CircleCI _organization_ can be one of three types: A CircleCI `circleci` organization:: You can create a `circleci` organization from your user homepage via the btn:[Create organization] button. #create guide to making a new org and link to it - retire support article?# -A CircleCI `github` organization:: A `github` organization used an OAuth app connection and is created when you log in to CircleCI using your GitHub account, rather than using your email/password or by connecting to GitHub Oauth app via menu:User Settings[Application Integrations]. #do we want to cover setting up one of these?# +A CircleCI `github` organization:: A `github` organization used an OAuth app connection and is created when you log in to CircleCI using your GitHub account, rather than using your email/password or by connecting to GitHub OAuth app via menu:User Settings[Application Integrations]. #do we want to cover setting up one of these?# A CircleCI `bitbucket` organization:: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account, rather than using your email/password or by connecting to Bitbucket OAuth app via menu:User Settings[Application Integrations].#do we want to cover setting up one of these?# For a guide to creating an organization, see #Add link when ready# -== Integration options - -The integration options available to you depend on your organization type, as follows: - -[cols=7*, options="header"] -|=== -| Organization type |GitHub App | GitHub OAuth | Bitbucket Cloud | Bitbucket Data Center | GitLab self managed | GitLab SaaS - -| `circleci` -| [.circle-green]#Yes# -| [.circle-red]#No# -| [.circle-red]#No# -| [.circle-green]#Yes# -| [.circle-green]#Yes# -| [.circle-green]#Yes# - -|`github` -| [.circle-green]#Yes# -| [.circle-green]#Yes# -| [.circle-red]#No# -| [.circle-red]#No# -| [.circle-red]#No# -| [.circle-red]#No# - -|`bitbucket` -| [.circle-red]#No# -| [.circle-red]#No# -| [.circle-green]#Yes# -| [.circle-red]#No# -| [.circle-red]#No# -| [.circle-red]#No# - -|=== - -== Disconnect a GitHub OAuth or Bitbucket Cloud account from your user 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/Bitbucket user account -* Changes to the organization name in your VCS -**** - -. From the link:https://app.circleci.com/[CircleCI web app], navigate to your **User Settings** by clicking on your user icon in the top bar. -. Select **Account Integrations**. -. You will see a list of connections along with the GitHub or Bitbucket organizations they are associated with. Select btn:[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. +#Org settings table here with tabs for different org types# == Projects @@ -169,6 +120,44 @@ For `circleci` type organizations, projects are created directly in CircleCI via -- ==== +#TODO Insert table of Project Settings for each org type# + +== Integration options + +The integration options available to you depend on your organization type. By _integration type_ we mean the way CircleCI checks out your code from your VCS provider. Options are as follows: + +#TODO would it be right to say that if you can integrate with GL SaaS you can with self managed? Then we can simplify this to "GitLab" and then say that integration type is the same as pipeline type?# + +[cols=7*, options="header"] +|=== +| Organization type |GitHub App | GitHub OAuth | Bitbucket Cloud | Bitbucket Data Center | GitLab self managed | GitLab SaaS + +| `circleci` +| [.circle-green]#Yes# +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-green]#Yes# +| [.circle-green]#Yes# +| [.circle-green]#Yes# + +|`github` +| [.circle-green]#Yes# +| [.circle-green]#Yes# +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-red]#No# + +|`bitbucket` +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-green]#Yes# +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-red]#No# + +|=== + == Quickstart The following links take you to the sections you need to get set up with CircleCI: @@ -201,7 +190,7 @@ A Bitbucket Cloud integration is built into a `bitbucket` type organization. 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 menu:User Settings[Account Integrations], select btn:[Disconnect] next to your Bitbucket Cloud integration and follow the instructions. -##GITLAB BBDC REMOVAL INSTRUCTIONS?# +#TODO GITLAB BBDC REMOVAL INSTRUCTIONS?# === Can I integrate a GitHub org with multiple CircleCI orgs? @@ -209,13 +198,13 @@ A GitHub org with the CircleCI GitHub App installed can only be integrated with In this scenario, attempting to integrate with a second CircleCI organization will redirect you to a GitHub App integration settings page when creating a project. If you are not sure what other CircleCI organization may be connected to your GitHub organization, you can submit a request link:https://forms.gle/dvcXN8ArByXqNNbJ7[here]. -#Benny can you help with this section?# +#TODO Benny can you help with this section?# image::guides:ROOT:github-app-configuration-page.png[Create a project] == Invite your team to your organization -#Add instructions for inviting for each org type# +For a guide to inviting you team see the xref:getting-started:invite-your-team.adoc[Invite your team] page. == Organization user permissions @@ -295,9 +284,12 @@ For full instructions on deleting organizations and projects, see the xref:secur 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. Each pipeline is defined by a configuration file stored in a repository (typically `.circleci/config.yml`). -The pipelines you have available to you depend on your organization type and where your code is stored. +The pipelines you can create and configure depend on your organization type and where your code is stored. + +#TODO there must be a better way to describe this# If you have a `circleci` organization: + * If your code is stored in a GitHub repository you can have GitHub App pipelines. * If your code is stored in a GitLab repository you can have GitLab pipelines. * If your code is stored in a Bitbucket Data Center repository you can set up Bitbucket Data Center pipelines. @@ -457,8 +449,93 @@ Bitbucket Data Center:: -- ==== +=== Custom checkout commands + +CircleCI provides a `checkout` step that is used to check out your source code. You find find more information about the special `checkout` step in the xref:reference:ROOT:configuration-reference.adoc#checkout[Configuration Reference] page. + +If you would rather use a custom checkout command you should 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 GitHub 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. + +[tabs] +==== +GitHub:: ++ +-- +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 +``` +-- +Bitbucket:: ++ +-- +When using a custom checkout command you will need to run the following commands: + +```shell +mkdir -p ~/.ssh + +echo 'bitbucket.org ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/VqLat/MaB33pZy0y3rJZtnqwR2qOOvbwKZYKiEO1O6VqNEBxKvJJelCq0dTXWT5pbO2gDXC6h6QDXCaHo6pOHGPUy+YBaGQRGuSusMEASYiWunYN0vCAI8QaXnWMXNMdFP3jHAJH0eDsoiGnLPBlBp4TNm6rYI74nMzgz3B9IikW4WVK+dc8KZJZWYjAuORU3jc1c/NPskD2ASinf8v3xnfXeukU0sJ5N6m5E8VLjObPEO+mN2t/FZTMZLiFqPWc/ALSqnMnnhwrNi2rbfg/rd/IpL8Le3pSBne8+seeFVBoGqzHM9yXw== +' >> ~/.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 bitbucket.com +# bitbucket.com:22 SSH-2.0-babeld-2e9d163d +bitbucket.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ== +# bitbucket.com:22 SSH-2.0-babeld-2e9d163d +# bitbucket.com:22 SSH-2.0-babeld-2e9d163d +➜ ~ ✗ +``` + +You can add the key to `known_hosts` by running the following command: +```shell +ssh-keyscan bitbucket.com >> ~/.ssh/known_hosts +``` +-- +==== + +== Best practices for SSH keys + +NOTE: This section is relevant to projects in a `github` or `bitbucket` type organization. + +This section describes best practices for using SSH keys in your CircleCI pipelines. + +* Use Deploy Keys whenever possible. +* When Deploy Keys cannot be used, <<#controlling-access-via-a-machine-user,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. See the xref:security:rotate-project-ssh-keys.adoc[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-github-user-key] -== Create a GitHub user key - GitHub OAuth and Bitbucket Cloud pipelines only +== Create a GitHub user key + +NOTE: If your organization is a `github` or `bitbucket` type organization, you can create a GitHub user key. Create a GitHub user key in CircleCI when you need write access to your GitHub repositories during your CI/CD pipeline, or when you need to access multiple repositories that your user account has access to. @@ -566,6 +643,30 @@ For a guide to additional SSH keys for CircleCI pipelines, see the xref:integrat The built-in environment variables available in a project depend on the pipeline type. For a full list see the xref:reference:ROOT:variables.adoc[Project values and variables] 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 link:https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users[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 DO need to check the implications and differences here for non- OAuth orgs - granting access in org settings > people for the machine user? Adding an additional SSH key?# + +NOTE: 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 link:https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users[instructions on GitHub]. + +. Log in to GitHub as the machine user. + +. Log in to the link:https://circleci.com/login[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. + [#Moving-from-github-oauth-app-to-github-app] == Moving from the GitHub OAuth app integration to the GitHub App integration @@ -641,8 +742,52 @@ If you are a GitHub organization owner or admin, you can enable third party acce NOTE: 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 link:https://github.com/settings/connections/applications/78a2ba87f071c28e65bb[GitHub Settings], and 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’ve approved CircleCI, you will see a checkmark next to your organization’s name. + +After access is granted, CircleCI should 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. + +. From the link:https://app.circleci.com/[CircleCI web app], navigate to your **User Settings** by clicking on your user icon in the top bar. +. Select **Account Integrations**. +. You will see a list of connections along with the GitHub or Bitbucket organizations they are associated with. Select btn:[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 === How do I delete my user account? -For guidance on deleting your user account link:https://support.circleci.com/hc/en-us/articles/360037058873-How-Do-I-Delete-My-User-Account#h_01JMMX9C1BAM445WCFZF56QMEE[see this support article]. \ No newline at end of file +For guidance on deleting your user account link:https://support.circleci.com/hc/en-us/articles/360037058873-How-Do-I-Delete-My-User-Account#h_01JMMX9C1BAM445WCFZF56QMEE[see this support article]. + +=== How do I delete an organization from CircleCI? + +See the xref:security:delete-organizations-and-projects.adoc[Delete organizations and projects] page for full instructions. + +#TO DO explain the different between deleting an OAuth org and disconnecting from user settings# \ No newline at end of file diff --git a/docs/guides/modules/security/pages/rename-organizations-and-repositories.adoc b/docs/guides/modules/security/pages/rename-organizations-and-repositories.adoc index 305c8b8366..33d97281e6 100644 --- a/docs/guides/modules/security/pages/rename-organizations-and-repositories.adoc +++ b/docs/guides/modules/security/pages/rename-organizations-and-repositories.adoc @@ -41,7 +41,7 @@ This page details everything you need to know about renaming organizations and r |=== -TIP: To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the xref:integration:github-apps-integration.adoc[GitHub App integration] page. +TIP: For a guide to organizations and integration types, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide]. [#github-app-or-gitlab] == GitHub App, GitLab, Bitbucket Data Center diff --git a/docs/guides/modules/security/pages/rotate-project-ssh-keys.adoc b/docs/guides/modules/security/pages/rotate-project-ssh-keys.adoc index 47dbf1b861..590b486c78 100644 --- a/docs/guides/modules/security/pages/rotate-project-ssh-keys.adoc +++ b/docs/guides/modules/security/pages/rotate-project-ssh-keys.adoc @@ -10,14 +10,14 @@ When using project SSH keys, CircleCI holds the private key, and the target syst [#github-projects] == GitHub projects -NOTE: To find out if your project uses the GitHub OAuth app or the CircleCI GitHub App, see the xref:integration:github-apps-integration.adoc[GitHub App integration] page. +include::ROOT:partial$tips/check-github-type-org.adoc[] Go to menu:Project Settings[SSH Keys] to view SSH keys set up for your project. [#rotate-a-deploy-key] -=== Rotate a deploy key (GitHub OAuth App) +=== Rotate a deploy key -Only relevant to projects using GitHub OAuth App: +This section is only relevant to projects in a `github` type organization: . Take note of the current key information to rotate, including the fingerprint. You can also click the keyname to open the related GitHub page that should list the public key. . Delete the deploy key by clicking the **X**. @@ -25,9 +25,11 @@ Only relevant to projects using GitHub OAuth App: . Go to GitHub’s repository project settings to delete the matching public key. The GitHub URL is typically `https://github.com///settings/keys`, or you may already have the page open if you clicked on the keyname in step 1. The keys are named `CircleCI`. Removing any key titled `CircleCI` created before the rotation is recommended. The new public SSH key will be automatically added once the old key is deleted. [#rotate-a-user-key-github-oauth-app] -=== Rotate a user key (GitHub OAuth App) +=== Rotate a user key -Only relevant to projects using GitHub OAuth App. If you have set up user keys for your project, follow these steps: +This section is only relevant to projects in a `github` type organization: + +If you have set up user keys for your project, follow these steps: . Take note of the current key information to rotate, including the fingerprint. You can also click the keyname to open the related GitHub page that should list the public key. . Delete the user key by clicking the **X**. @@ -39,9 +41,9 @@ CAUTION: The user key name contains the project name, however, a user key may gi NOTE: If using organization SSO, take note of which org is currently authorized. If access is needed for the newly created key, you will need to reauthorize it. [#rotate-an-additional-SSH-key-github-oauth-app-and-github-app] -=== Rotate an additional SSH key (GitHub OAuth App & GitHub App) +=== Rotate an additional SSH key -Relevant to projects that use the GitHub OAuth App and projects that use the CircleCI GitHub App. If you are using additional SSH keys in your project, follow these steps: +If you are using additional SSH keys in your project, follow these steps: . Take note of the existing key to know which target system it is used for, and the fingerprint for your records. This could be a VCS, a machine, or another SSH based system. . Delete the SSH key by clicking the **X**. @@ -51,7 +53,7 @@ Relevant to projects that use the GitHub OAuth App and projects that use the Cir . Authorize the target system to use the new key. [#bitbucket-projects] -== Bitbucket projects +== Bitbucket Cloud projects Go to **Project Settings > SSH Keys** to view SSH keys set up for your project. diff --git a/docs/guides/modules/test/pages/test-splitting-tutorial.adoc b/docs/guides/modules/test/pages/test-splitting-tutorial.adoc index 9e1ec6d0fe..961b07e453 100644 --- a/docs/guides/modules/test/pages/test-splitting-tutorial.adoc +++ b/docs/guides/modules/test/pages/test-splitting-tutorial.adoc @@ -78,11 +78,13 @@ Test splitting is typically set up within a job. In this tutorial you will modif [#step-one-add-the-project] == 1. Add the project -To get started, you need to get the sample app building as a project on CircleCI. If you are using GitHub the steps are slightly different depending on whether you have a GitHub OAuth app or CircleCI GitHub App integration. To find out which integration you have, see the xref:integration:github-apps-integration.adoc[GitHub App integration] page. +To get started, you need to get the sample app building as a project on CircleCI. + +The steps are a little different depemding on which organization type you have: `circleci`, `github` or `bitbucket`. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide] for more information. [tabs] ==== -GitHub Oauth app:: +`github` type organization:: + -- . link:https://github.com/CircleCI-Public/circleci-react-test-splitting-tutorial/fork[Fork the repository] on GitHub. @@ -122,7 +124,7 @@ Feel free to take a look at the steps run in the pipeline by expanding the green + image::guides:ROOT:test-splitting-first-setup-steps.png[Steps run successfully within the job] -- -Bitbucket Cloud:: +`bitbucket` type organization:: + -- . Import the project code into Bitbucket, using the repo URL: `https://github.com/CircleCI-Public/circleci-react-test-splitting-tutorial` @@ -162,7 +164,7 @@ Feel free to take a look at the steps run in the pipeline by expanding the green + image::guides:ROOT:test-splitting-first-setup-steps.png[Steps run successfully within the job] -- -GitHub App, GitLab, Bitbucket Data Center:: +`circleci` type organization:: + -- . link:https://github.com/CircleCI-Public/circleci-react-test-splitting-tutorial/fork[Fork the repository] if you are using GitHub, or import to Bitbucket or GitLab using the repository URL: `https://github.com/CircleCI-Public/circleci-react-test-splitting-tutorial` diff --git a/docs/guides/modules/toolkit/pages/get-started-with-the-vs-code-extension.adoc b/docs/guides/modules/toolkit/pages/get-started-with-the-vs-code-extension.adoc index 5bd047359e..d25ac70758 100644 --- a/docs/guides/modules/toolkit/pages/get-started-with-the-vs-code-extension.adoc +++ b/docs/guides/modules/toolkit/pages/get-started-with-the-vs-code-extension.adoc @@ -45,7 +45,7 @@ If your VS Code workspace contains one or more CircleCI projects, the extension If no project is detected, open the extension's settings page (either through the VS Code command `CircleCI: Open Settings`, or by clicking on the settings icon image:guides:ROOT:icons/settings.svg[settings icon, role="no-border"] at the top of the pipelines panel), and select your projects manually. Only projects you follow are listed for selection. -NOTE: **GitHub App and GitLab projects:** The pipelines manager does not yet support automatic detection for xref:integration:github-apps-integration.adoc[GitHub App] and xref:integration:gitlab-integration.adoc[GitLab] projects. Select your project manually from the settings page. +NOTE: **GitHub App and GitLab projects:** The pipelines manager does not yet support automatic detection for projects in a `circleci` type organization. Select your project manually from the settings page. FOr more information on organization types, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide]. image::guides:ROOT:vs_code_extension_pipelines_panel_zoomed.png[The pipelines panel displays pipelines you follow.] @@ -85,7 +85,7 @@ Alternatively, you can configure SSH keys for the extension manually through the To open an SSH session in a dedicated VS Code remote window, you need to install the link:https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-explorer[official Remote Explorer extension for VS Code]. -NOTE: **GitHub App and GitLab projects:** Re-run with SSH from VS Code is not yet available for xref:integration:github-apps-integration.adoc[GitHub App] and xref:integration:gitlab-integration.adoc[GitLab] projects. +NOTE: **GitHub App and GitLab projects:** Re-run with SSH from VS Code is not yet available for projects in a `circleci` type organization. For more information on organization types, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide]. image::guides:ROOT:vs_code_extension_ssh_remote_window.png[VS Code with remote development window] diff --git a/docs/guides/modules/toolkit/pages/vs-code-extension-overview.adoc b/docs/guides/modules/toolkit/pages/vs-code-extension-overview.adoc index 2be441f11d..ff2788b944 100644 --- a/docs/guides/modules/toolkit/pages/vs-code-extension-overview.adoc +++ b/docs/guides/modules/toolkit/pages/vs-code-extension-overview.adoc @@ -13,7 +13,7 @@ The VS Code extension includes: - The **Pipeline Manager**, which lets you view and manage pipelines within the IDE (integrated development environment). The pipeline manager allows you to identify issues and take immediate action on your pipelines without switching between VS Code and your browser. - The **Config Helper**, which provides in-file help with navigating, writing, and editing configuration files. -NOTE: Currently only the **Config Helper** is available for GitLab and GitHub App projects. To find out if you authenticated through the GitHub OAuth app or the CircleCI GitHub App, see the xref:integration:github-apps-integration.adoc[GitHub App integration] page. +NOTE: Currently only the **Config Helper** is available for projects in a `circleci` type organization. For more information on organization types, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide]. [#install-the-vs-code-extension] == Install the VS Code extension @@ -65,7 +65,7 @@ Expanding a job also lets you: [#re-run-with-ssh] === Re-run with SSH -NOTE: **GitHub App and GitLab projects:** Re-run with SSH from VS Code is not yet available for xref:integration:github-apps-integration.adoc[GitHub App] and xref:integration:gitlab-integration.adoc[GitLab] projects. +NOTE: **GitHub App and GitLab projects:** Re-run with SSH from VS Code is not yet available for projects in a `circleci` type organization. For more information on organization types, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide]. Re-run jobs with SSH directly from VS Code in one of two ways: diff --git a/docs/orbs/modules/author/pages/create-an-orb.adoc b/docs/orbs/modules/author/pages/create-an-orb.adoc index 505035e3e5..b955899864 100644 --- a/docs/orbs/modules/author/pages/create-an-orb.adoc +++ b/docs/orbs/modules/author/pages/create-an-orb.adoc @@ -89,7 +89,7 @@ NOTE: If you would like a convenient way to download the link:https://github.com ==== GitHub App integration additional steps -If your GitHub account is authorised with CircleCI using the GitHub App integration, you will need to follow some extra steps, as listed below. To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the xref:guides:integration:github-apps-integration.adoc[GitHub App integration] page. +If you have a `circleci` type organization you will need to follow some extra steps, as listed below. For more information on organization types, see the xref:guides:permissions-authentication:users-organizations-and-integrations-guide.adoc[Users, organizations, and integrations guide]. * When prompted, `Are you using GitHub or Bitbucket or GitHub app (if GH App use circleci as the entry)?`, enter `circleci`. * When prompted, `Enter your circleci username or organization`, you will need to inspect the URL from the CircleCI web app and provide the org ID portion: diff --git a/docs/reference/modules/ROOT/pages/glossary.adoc b/docs/reference/modules/ROOT/pages/glossary.adoc index 46d3a68ba9..b57cefe9f2 100644 --- a/docs/reference/modules/ROOT/pages/glossary.adoc +++ b/docs/reference/modules/ROOT/pages/glossary.adoc @@ -75,9 +75,11 @@ The user who adds a repository in the VCS to CircleCI as a project. [#project] == Project -For xref:guides:integration:github-integration.adoc[GitHub OAuth app] and xref:guides:integration:bitbucket-integration.adoc[Bitbucket Cloud] accounts, a CircleCI project shares the name of the code repository for which it automates workflows, tests, and deployment. A project is visible on the **Projects** page of the https://app.circleci.com/[CircleCI web app] and must be added with the **Set Up Project** button. +include::guides:ROOT:partial$tips/check-org-type.adoc[] -For xref:guides:integration:github-apps-integration.adoc[GitHub App], xref:guides:integration:gitlab-integration.adoc[GitLab] and xref:guides:integration:bitbucket-data-center-integration.adoc[Bitbucket Data Center] accounts, a CircleCI project is a standalone entity that you first create, and then associate with a code repository. You can create projects and connect your code in the link:https://app.circleci.com/[CircleCI web app]. +For `github` and `bitbucket` type organizations, a CircleCI project shares the name of the code repository for which it automates workflows, tests, and deployment. A project is visible on the **Projects** page of the https://app.circleci.com/[CircleCI web app] and must be added with the **Set Up Project** button. + +For `circleci` type organizations, a CircleCI project is a standalone entity that you first create, and then associate with a code repository. You can create projects and connect your code in the link:https://app.circleci.com/[CircleCI web app]. After a project is set up or created, it is possible to configure settings, contexts, environment variables, and team members who may follow the project. Following a project enables you to subscribe to email notifications for the project's build status, and adds the project to your CircleCI dashboard. diff --git a/docs/reference/modules/ROOT/pages/outbound-webhooks-reference.adoc b/docs/reference/modules/ROOT/pages/outbound-webhooks-reference.adoc index 172466b4a8..f151c9ff0f 100644 --- a/docs/reference/modules/ROOT/pages/outbound-webhooks-reference.adoc +++ b/docs/reference/modules/ROOT/pages/outbound-webhooks-reference.adoc @@ -210,7 +210,7 @@ The following data about the trigger associated with the webhook event is provid [#trigger-parameters] === Trigger parameters -NOTE: Data associated to the pipeline. Present for pipelines associated with GitLab, GitHub App, or Bitbucket Data Center. For parameters available for GitHub OAuth app and Bitbucket Cloud integrations, see <<#vcs>> below. To find out which GitHub integration you have, see the xref:guides:integration:github-apps-integration.adoc[GitHub Apps integration] page. +NOTE: Data associated to the pipeline. Present for pipelines associated with GitLab, GitHub App, or Bitbucket Data Center. For parameters available for GitHub OAuth app and Bitbucket Cloud integrations, see <<#vcs>> below. Check menu:Project Settings[Project setup] or menu:Project Settings[Pipelines] to see your pipeline type. [cols="1,1,2", options="header"] |=== @@ -260,7 +260,7 @@ NOTE: Data associated to the pipeline. Present for pipelines associated with Git [#vcs] === VCS -NOTE: The VCS map and its contents are always present for GitHub OAuth app and Bitbucket Cloud projects, but not for GitLab, GitHub App or Bitbucket Data Center projects. See <<#trigger-parameters,trigger parameters>> above for GitLab, GitHub App or Bitbucket Data Center parameters. To find out which GitHub integration you have, see the xref:guides:integration:github-apps-integration.adoc[GitHub Apps integration] page. +NOTE: The VCS map and its contents are always present for GitHub OAuth app and Bitbucket Cloud pipelines, but not for GitLab, GitHub App or Bitbucket Data Center pipelines. See <<#trigger-parameters,trigger parameters>> above for GitLab, GitHub App or Bitbucket Data Center parameters. To find out which pipeline type you have, check menu:Project Settings[Project setup] or menu:Project Settings[Pipelines]. [cols="1,1,2", options="header"] |=== @@ -324,7 +324,7 @@ NOTE: The VCS map and its contents are always present for GitHub OAuth app and B [#sample-webhook-payloads] == Sample webhook payloads -NOTE: To find out which GitHub integration you have, see the xref:guides:integration:github-apps-integration.adoc[GitHub Apps integration] page. +NOTE: To find out which pipeline type you have, check menu:Project Settings[Project setup] or menu:Project Settings[Pipelines]. [#workflow-completed-for-github-and-bitbucket] === `workflow-completed` for GitHub OAuth and Bitbucket Cloud diff --git a/docs/reference/modules/ROOT/pages/variables.adoc b/docs/reference/modules/ROOT/pages/variables.adoc index 892d38b1f8..494ad5f72a 100644 --- a/docs/reference/modules/ROOT/pages/variables.adoc +++ b/docs/reference/modules/ROOT/pages/variables.adoc @@ -258,7 +258,7 @@ build: Pipeline values are available to all pipeline configurations and can be used without previous declaration. Pipeline values are scoped at the pipeline level. They are interpolated at compilation time, not workflow/job runtime. -NOTE: For GitHub users, refer to the xref:guides:integration:github-apps-integration.adoc[GitHub App integration] or xref:guides:integration:github-integration.adoc[GitHub OAuth app integration] guides to check which integration type applies to you. +The pipeline values available to you depend on your pipeline/integration type, as shown in the "Source" column of the table below. include::guides:ROOT:partial$pipelines-and-triggers/pipeline-values.adoc[] From 58e284a0c8c4c789fdd69d20bd0e10910d601fb0 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Thu, 6 Nov 2025 12:29:02 +0000 Subject: [PATCH 09/23] remove incorrectly placed alias --- archive/github-apps-integration.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/archive/github-apps-integration.adoc b/archive/github-apps-integration.adoc index 9e4ffa62c3..d57b533b49 100644 --- a/archive/github-apps-integration.adoc +++ b/archive/github-apps-integration.adoc @@ -2,7 +2,6 @@ :page-platform: Cloud :page-description: Learn how to integrate CircleCI with GitHub using GitHub Apps. :experimental: -:page-alias: guides:integration:github-apps-integration.adoc If your CircleCI organization is integrated with GitHub through the **CircleCI GitHub App**, the content on this page is for you. From 2a75973aff58e8f119ffc67deaca6756988763a9 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Wed, 12 Nov 2025 10:42:56 +0000 Subject: [PATCH 10/23] add a page to create an organization --- docs/guides/modules/ROOT/nav.adoc | 1 + .../pages/create-an-organization.adoc | 51 +++++++ ...-organizations-and-integrations-guide.adoc | 134 ++++++++++++++++-- 3 files changed, 177 insertions(+), 9 deletions(-) create mode 100644 docs/guides/modules/getting-started/pages/create-an-organization.adoc diff --git a/docs/guides/modules/ROOT/nav.adoc b/docs/guides/modules/ROOT/nav.adoc index ed46cabefc..a859227ba0 100644 --- a/docs/guides/modules/ROOT/nav.adoc +++ b/docs/guides/modules/ROOT/nav.adoc @@ -18,6 +18,7 @@ *** xref:getting-started:language-javascript.adoc[Node.js quickstart] *** xref:getting-started:language-python.adoc[Python quickstart] *** xref:getting-started:language-go.adoc[Go quickstart] +*** xref:getting-started:create-an-organization.adoc[Create an organization] ** Tutorials *** xref:getting-started:config-intro.adoc[Configuration intro] *** xref:getting-started:slack-orb-tutorial.adoc[Use the Slack orb to set up notifications] diff --git a/docs/guides/modules/getting-started/pages/create-an-organization.adoc b/docs/guides/modules/getting-started/pages/create-an-organization.adoc new file mode 100644 index 0000000000..7a1dd7f6db --- /dev/null +++ b/docs/guides/modules/getting-started/pages/create-an-organization.adoc @@ -0,0 +1,51 @@ += Create an organization +:page-platform: Cloud +:page-description: Create a new organization in CircleCI. +:experimental: + +This guide coverts creating a new organization in CircleCI. + +The following organization types are available in CircleCI: + +* `circleci` organizations +* `github` organizations +* `bitbucket` organizations + +== Create a `circleci` organization + +To create a `circleci` organization, follow these steps: + +. Navigate to your user homepage in the link:https://app.circleci.com/home/[CircleCI web app]. +. Select the btn:[+ Create organization] button. +. Give your organization a name and select btn:[Let's Go]. + +Once your new organization is created you can start creating projects and inviting team members: + +* xref:create-project.adoc#create-a-project[Create a project] +* xref:invite-your-team.adoc#invite-teammates[Invite your team] + +== Create a `github` organization + +A `github` organization is created when you log in to CircleCI using your _social_ GitHub login. `github` organizations use an OAuth app connection with CircleCI. If you have logged in to CircleCI using a method other than your GitHub login, you can still create a `github` organization by following these steps: + +. Navigate to your link:https://app.circleci.com/settings/user[User settings] page. +. Select the **Account Integrations** from the sidebar. +. At the bottom of the page, select the link that reads `Recieved instructions from the CircleCI Support team to authorize a GitHub OAuth app?` +. Follow the instructions to create a `github` organization. + +Once your `github` organization is created you can start setting up and following projects: + +* xref:create-project.adoc#set-up-a-project[Set up a project] + +== Create a `bitbucket` organization + +A `bitbucket` organization is created when you log in to CircleCI using your _social_ Bitbucket login. `bitbucket` organizations use an OAuth app connection with CircleCI. If you have logged in to CircleCI using a method other than your Bitbucket login, you can still create a `bitbucket` organization by following these steps: + +. Navigate to your link:https://app.circleci.com/settings/user[User settings] page. +. Select the **Account Integrations** from the sidebar. +. Select btn:[Connect] next to Bitbucket. +. Follow the instructions to authorize the Bitbucket OAuth app. + +Once your `bitbucket` organization is created you can start setting up and following projects: + +* xref:create-project.adoc#set-up-a-project[Set up a project] \ No newline at end of file diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 816f095e93..fe000ba655 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -10,15 +10,17 @@ This guide explains the concepts of user, organization, and integration in Circl When you log in to CircleCI you are logging in to your _user account_. -As a CircleCI _user_ you can access _organizations_. You can access zero, one or many organizations. You can create new organizations and/or join an existing organization. +As a CircleCI _user_ you can create and access _organizations_. You can access zero, one, or many organizations. You can create new organizations and/or join an existing organization. You can log in to CircleCI using one of the following methods: * Email and password * Social login (GitHub, Bitbucket) -Select your icon in the top bar and select **User settings** to access the following sections: +Select your icon in the top bar and select **User settings** to access the following: +[.table-scroll] +-- .User settings [cols="1,2", options="header"] |=== @@ -52,6 +54,7 @@ Select your icon in the top bar and select **User settings** to access the follo | Opt in to CircleCI's beta program. Beta features you opt in to will be listed on this page. |=== +-- == Organizations @@ -68,13 +71,61 @@ Each organization has its own settings, including security, integrations, and re A CircleCI _organization_ can be one of three types: -A CircleCI `circleci` organization:: You can create a `circleci` organization from your user homepage via the btn:[Create organization] button. #create guide to making a new org and link to it - retire support article?# -A CircleCI `github` organization:: A `github` organization used an OAuth app connection and is created when you log in to CircleCI using your GitHub account, rather than using your email/password or by connecting to GitHub OAuth app via menu:User Settings[Application Integrations]. #do we want to cover setting up one of these?# -A CircleCI `bitbucket` organization:: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account, rather than using your email/password or by connecting to Bitbucket OAuth app via menu:User Settings[Application Integrations].#do we want to cover setting up one of these?# +A CircleCI `circleci` organization:: This organization type is created separately to any VCS connection between CircleCI and your code repositories. Within a `circleci` organization you create projects and then connect them to your code repositories. +A CircleCI `github` organization:: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. +A CircleCI `bitbucket` organization:: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account. Your Bitbucket repositories appear as projects that can be set up in CircleCI. + +For full details on creating organizations, see the xref:getting-started:create-an-organization.adoc[Create an organization] page. + +The following organization settings are available: + +[.table-scroll] +-- +[cols="1,2", options="header"] +|=== +| Organization settings section | What you will find here + +| Overview +| Org ID and slug, option to rename or delete the organization. Manage technical and security contacts. + +| People +| For `circleci` organizations find a list of organization members and their roles. For all organizations you will find the option to invite new members to the organization. + +|Groups +| `circleci` organizations only. Create and manage groups of org members. You can assign roles to groups to manage permissions. + +| Contexts +| Create and manage contexts to store sensitive information. You can use contexts to store environment variables for your projects. -For a guide to creating an organization, see #Add link when ready# +| VCS Connections +| View Apps you have installed for your organization: GitHub App and GitHub Checks App. -#Org settings table here with tabs for different org types# +| Security +| Orb security settings, you can choose to allow just certified orbs, all orbs, and choose to allow private orbs. Request audit logs and/or set up audit log streaming. + +| Policies +| Find a list of policis that have been created for your organization. + +| Advanced +| Opt in/out of the following: intelligent summaries for build failures, image brownouts, triggering pipelines with unversioned config. + +| Orbs +| For `circleci` organizations you will find your URL orb allow list. FOr `github` and `bitbucket` organizations you will find registry information for orbs that have been authored by your organization. + +| Self-hosted runners +| Set up self-hosted runners for your organization, to build on your own infrastructure. + +| Deploys +| Find information on setting up deploys and/or the release agent. + +| Integrations +| `circleci` organizations only. Integration set up for GitLab self-managed and Bitbucket Data Center. + +| Singe sign-on +| `circleci` organizations on Scale Planonly. Set up SSO for your organization. + +|=== +-- == Projects @@ -120,7 +171,63 @@ For `circleci` type organizations, projects are created directly in CircleCI via -- ==== -#TODO Insert table of Project Settings for each org type# +The following project settings are available: + +[.table-scroll] +-- +[cols="1,2", options="header"] +|=== +| Project settings section | What you will find here + +| Overview +| Project name, ID, and slug. Option to stop building or delete the project. + +| Project setup +| `circleci` and `github` organizations only. Add and manage pipelines and their triggers. Projects for other organization types will have separate Pipelines and Triggers pages. + +| People +| `circleci` organizations only. Assign project-level roles to your team. + +| Deploys +| Set up deploy markers, rollback pipeline and find information about setting up the release agent for Kubernetes deployments. + +| Advanced +a| Enable/disable various features for the project: +* GitHub status updates +* Build forked PRs +* Pass secrets to forked PRs +* Only build pull requests +* Auto-cancel redundant workflows +* Free and open source +* Enable dynamic configuration +* Disable SSH reruns. + +| Environment variables +| Add project environment variables. Youc an add individually or import from another project. You will find a list of project environment variables on this page. + +| SSH keys +| Add deploy and user keys for `github` and `bitbucket` organizations. Add additional SSH keys for your project for all organization types. + +| API permissions +| Create project API tokens. The main use for these tokens is for status badges. Some API v1.1 endpoints support the use of project API tokens too. + +| LLMOps +| Connect your project with an LLM evaluations provider. + +| Slack integration +| Get information on setting up Slack notifications for your project. + +| Status badges +| Generate a code snippet that will display your project's build status in a README or other document. + +| Webhooks +| Set up webhooks through CircleCI's Webhook API. This allows you to connect a platform you manage (either an API you create yourself, or a third party service) to a stream of future events. + +| Docker layer caching +| Provides an option to delete your cache contents. If jobs that use DLC continuously fail, this may be due to a corrupted cache. Deleting the cache will force a fresh build and can solve the problem. + +|=== +-- == Integration options @@ -158,6 +265,15 @@ The integration options available to you depend on your organization type. By _i |=== +=== Limitations + +The following limits are currently in place: + +- Each user can create up to three `circleci` organizations. +- Each `circleci` organization under a Free Plan can have up to 10 projects. + +If you need more organizations or projects, consider upgrading to a xref:plans-pricing:plan-overview.adoc[Paid plan], or link:https://support.circleci.com/hc/en-us/requests/new[contact our Support team]. + == Quickstart The following links take you to the sections you need to get set up with CircleCI: @@ -190,7 +306,7 @@ A Bitbucket Cloud integration is built into a `bitbucket` type organization. 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 menu:User Settings[Account Integrations], select btn:[Disconnect] next to your Bitbucket Cloud integration and follow the instructions. -#TODO GITLAB BBDC REMOVAL INSTRUCTIONS?# +#TODO GITLAB BBDC REMOVAL INSTRUCTIONS? We need equivalent instructions for GitLab SaaS, self-managed and BBDC here# === Can I integrate a GitHub org with multiple CircleCI orgs? From 8bc0edb0034ada97a1458eb4f73c8adf5ccab3fb Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Thu, 13 Nov 2025 10:44:43 +0000 Subject: [PATCH 11/23] add tabs for additional ssh keys --- ...-organizations-and-integrations-guide.adoc | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index fe000ba655..ee464131cf 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -725,6 +725,11 @@ You may need to add additional SSH keys to your pipelines. Some examples of when If you need additional SSH keys in your builds, follow these steps: +[tabs] +==== +GitHub:: ++ +-- 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`. . Create an SSH key-pair by following the link:https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/[GitHub instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): @@ -752,6 +757,69 @@ $ ssh-keygen -t ed25519 -C "your_email@example.com" ``` When you push to your GitHub repository from a job, CircleCI will use the SSH key you added. +-- +Bitbucket:: ++ +-- +In this example, the Bitbucket Cloud repository is `https://bitbucket.org/you/test-repo/src/main/`, and the CircleCI project is `https://app.circleci.com/pipelines/bitbucket/you/test-repo`. + +. Create an SSH key-pair by following the link:https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/[Bitbucket instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): ++ +```shell + ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +. Go to `https://bitbucket.org/you/test-repo/admin/access-keys/`, and select **Add key**. Enter a label in the "Label" field, then copy and paste the public key you created in step 1. Select **Add SSH key**. + +. Go to your project settings in the CircleCI app, select **SSH Keys**, and **Add SSH key**. In the "Hostname" field, enter `bitbucket.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: ++ +```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 Bitbucket Cloud repository from a job, CircleCI will use the SSH key you added. +-- +GitLab:: ++ +-- +When creating a GitLab-based project in CircleCI, an SSH key is created, which is used to check out code from your repository. Each configuration you create generates a new SSH key to access the code in the repository associated with that configuration. At this time, only **Additional SSH Keys** are applicable to GitLab projects. + +. Create an SSH key-pair by following the link:https://docs.gitlab.com/ee/user/ssh.html[GitLab instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): ++ +```shell + ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +. Go to your project on link:https://gitlab.com/[GitLab] and navigate to **Settings > Repository**, and expand the **Deploy keys** section. Enter a title in the "Title" field, then copy and paste the public key you created in step 1. Check **Grant write permissions to this key** box, 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 `gitlab.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: ++ +```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 GitLab repository from a job, CircleCI will use the SSH key you added. + +-- +==== For a guide to additional SSH keys for CircleCI pipelines, see the xref:integration:add-ssh-key.adoc[Add SSH keys] page. From 0f895068217fbbbe72336408e93e0e48bda91bee Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Fri, 14 Nov 2025 14:09:59 +0000 Subject: [PATCH 12/23] work on integration guide for GitLab self-managed and bbdc --- .../getting-started/pages/create-project.adoc | 8 +- ...-organizations-and-integrations-guide.adoc | 153 +++++++++++++++++- .../delete-organizations-and-projects.adoc | 2 +- 3 files changed, 157 insertions(+), 6 deletions(-) diff --git a/docs/guides/modules/getting-started/pages/create-project.adoc b/docs/guides/modules/getting-started/pages/create-project.adoc index 71556a4065..e9f84b7f6b 100644 --- a/docs/guides/modules/getting-started/pages/create-project.adoc +++ b/docs/guides/modules/getting-started/pages/create-project.adoc @@ -69,6 +69,9 @@ Once your project is created you will land on your pipelines page. GitLab Cloud:: + -- + +NOTE: **Remove GitLab CI/CD config** You should remove the `.gitlab-ci.yml` file from projects you integrate with CircleCI. This prevents you from having CI/CD builds happening in both systems. There is an option to _disable_ GitLab CI/CD for a project in the GitLab UI but using this is **not recommended**. + Follow these steps to create a new project in CircleCI: include::ROOT:partial$create-project/steps-up-to-pipeline.adoc[Insert steps from selecting Create project up to setting up a pipeline] @@ -107,6 +110,9 @@ image::guides:ROOT:create-project/download-config-file.png[Modal showing options GitLab self-managed:: + -- + +NOTE: **Remove GitLab CI/CD config** You should remove the `.gitlab-ci.yml` file from projects you integrate with CircleCI. This prevents you from having CI/CD builds happening in both systems. There is an option to _disable_ GitLab CI/CD for a project in the GitLab UI but using this is **not recommended**. + Follow these steps to create a new project in CircleCI: include::ROOT:partial$create-project/steps-up-to-pipeline.adoc[Insert steps from selecting Create project up to setting up a pipeline] @@ -127,7 +133,7 @@ image::guides:ROOT:create-project/create-new-gitlab-self-managed-project.png[Cre **** If this is your first GitLab self-managed project you will now set up your integration: -* Verify your GitLab URL +* Verify your GitLab URL. The field will automatically append `/api/v4`, so the URL that CircleCI uses to connect to your account looks something like `https://test-gitlab.circleci.com/api/v4`. * Generate an add a personal access token * Add your known hosts, following the instructions in the app **** diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index ee464131cf..35be418cd4 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -235,6 +235,8 @@ The integration options available to you depend on your organization type. By _i #TODO would it be right to say that if you can integrate with GL SaaS you can with self managed? Then we can simplify this to "GitLab" and then say that integration type is the same as pipeline type?# +[.table-scroll] +-- [cols=7*, options="header"] |=== | Organization type |GitHub App | GitHub OAuth | Bitbucket Cloud | Bitbucket Data Center | GitLab self managed | GitLab SaaS @@ -264,12 +266,144 @@ The integration options available to you depend on your organization type. By _i | [.circle-red]#No# |=== +-- + +Integrations are set up as follows: + +* GitHub App and GitLab SaaS are set up when creating a project. +* GitHub OAuth and Bitbucket Cloud are set up when logging in to CircleCI with your GitHub or Bitbucket social login. +* GitLab self-managed and Bitbucket Data Center are set up from menu:Organization Settings[Integrations]. + +=== GitLab self-managed integration setup + +You will set up an integration with your GitLab self-managed instance when creating a project. You will need: + +* Your GitLab self-managed instance URL, for example, `https://test-gitlab.circleci.com`. ++ +Your self-managed instance must already contain at least one GitLab project. The authorization attempt will be unsuccessful if your instance does not have any projects. Note that the self-managed instance must be accessible via the public internet. If the self-managed instance is behind a firewall, see link:https://discuss.circleci.com/t/gitlab-self-managed-support-on-circleci-is-now-here/47726/3?u=sebastian-lerner[a suggested workaround]. + +* A link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html[personal access token]. This token must have the `api` scope. + +[#known-hosts-input] +* 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 should look 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 +``` + +Once you have integrated your CircleCI organization with your GitLab self-managed instance, you will be able to see the integration in menu:Organization Settings[Integrations]. From here you can add integrations to other GitLab self-managed instances you have access to, as follows: + +. Navigate to menu:Organization Settings[Integrations] to add a new instance. ++ +image::guides:ROOT:gl-sm-integrations.png[Add a new self-managed instance on the Integrations page] + +. You will need to enter the instance URL, as described in the xref:#sign-up[Sign up] section above. + +NOTE: The ability to edit or delete existing integrations is not currently supported. -=== Limitations +For GitLab.com, account integrations can be managed under your xref:#user-account-integrations[user settings]. -The following limits are currently in place: +NOTE: If you are using both CircleCI's Bitbucket Data Center and GitLab self-managed integrations, there is a known bug in the menu:Organization Settings[Integrations] section of the CircleCI web app. Adding a `known_hosts` to one integration will populate the `known_hosts` for the other integration. To use both Bitbucket Data Center and GitLab self-managed integrations within the same CircleCI organization, add both respective `known_hosts` values to the one input field separated by a new line. -- Each user can create up to three `circleci` organizations. +=== Bitbucket Data Center integration setup + +. **Set up your integration with Bitbucket Data Center if you have not already**: +.. In the CircleCI web app, select **Organization Settings** in the sidebar. +.. Select **Integrations** in the sidebar. +.. Select btn:[Set Up Integration] next to Bitbucket Data Center. +.. In the modal, enter your Bitbucket Data Center instance URL and your known_hosts. For guidance on generating known_hosts, see <>. ++ +NOTE: If you are using both CircleCI's Bitbucket Data Center and GitLab self-managed integrations, there is a known bug in the menu:Organization Settings[Integrations] section of the CircleCI web app. Adding a `known_hosts` to one integration will populate the `known_hosts` for the other integration. To use both Bitbucket Data Center and GitLab self-managed integrations within the same CircleCI organization, add both respective `known_hosts` values to the one input field separated by a new line. + +.. Select btn:[Set Up Integration]. +.. Select the back arrow to exit **Organization Settings**. + +. For the next sections 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 link:https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html[Bitbucket docs]. Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI. + +. **Set up a pipeline**: +.. Select **Project Settings**. +.. Select **Pipelines** in the sidebar. +.. Select **Set Up Pipeline**. Fill in the required fields: +** Give your pipeline a descriptive name. +** Select **Bitbucket Data Center** under Integration. +** Provide the project HTTP access token you created in the previous step. Select btn:[Connect]. +** Under Config, define where the config file for this pipeline is stored: +*** Select a repository from the dropdown. +*** Enter the path to the config file. Typically this is `.circleci/config.yml` but can be any file path with extension `*.yml`. +** Under Build Assets, select a checkout source for this pipeline. This is the repository that will be checked out when a link:https://circleci.com/docs/configuration-reference/#checkout[checkout step] is run. If your config is stored in the same repository as your code, pick the same repository you selected under Config Source. +.. Select btn:[Save]. + +. **Set up a trigger**: +.. Select **Triggers** in the Project Settings sidebar. +.. Select **Add Trigger**. +.. Select Bitbucket Data Center from the dropdown and select btn:[Next]. +.. Fill in the required fields: +** Give your trigger a descriptive name. +** Provide the project HTTP access token you created above. Select btn:[Connect]. +** Select the Trigger source repository +** Choose the pipeline you created in the previous step under the dropdown to show CircleCI which pipeline to trigger. +** If prompted, enter a config branch. This is the name of the branch that should be used to fetch your config file when a pipeline is triggered. This field is only required if your config is stored in a repository that is not the source of your trigger. +** If prompted, enter a checkout branch. This is the name of the branch that should be used to check out your code when a link:https://circleci.com/docs/configuration-reference/#checkout[checkout step] is run. This field is only required if the Checkout Source repository you configured in your Pipeline is not the source of your trigger. + +.. Select btn:[Save]. + +. If you have not already done so, **create a `.circleci` directory to the root of your repository, then add a `config.yml` file in that directory**. When you commit this change in your repository, you should see the pipeline trigger for the first time on the CircleCI dashboard. ++ +**** +For help with creating a CircleCI `config.yml`, see the following pages: + +* xref:getting-started:hello-world.adoc[Hello world] +* xref:toolkit:sample-config.adoc[Sample config] +* xref:reference:ROOT:configuration-reference.adoc[Configuration reference] +**** + +Each time you push changes to your Bitbucket Data Center repository, a new pipeline is triggered and you should see it running for the project within the CircleCI web app. + +image::guides:ROOT:gl-ga/gitlab-ga-successful-pipeline.png[Successful pipeline run] + +Make any further changes to your CircleCI config in your Bitbucket Data Center repository. Editing an existing CircleCI configuration within the web app is not currently available. + +Committing changes in your repository will automatically trigger a pipeline. Manually triggering a pipeline from the CircleCI web app is not available at this time. + +[#known-hosts] +=== Generate `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: + +TIP: 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 menu:Organization Settings[Integrations]. + +== Limitations + +The following limits are currently in place for the Free Plan: + +- Each user can create up to three `circleci` organizations on the Free Plan. - Each `circleci` organization under a Free Plan can have up to 10 projects. If you need more organizations or projects, consider upgrading to a xref:plans-pricing:plan-overview.adoc[Paid plan], or link:https://support.circleci.com/hc/en-us/requests/new[contact our Support team]. @@ -573,7 +707,7 @@ If you would rather use a custom checkout command you should follow the steps be ==== 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 GitHub 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 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. [tabs] ==== @@ -634,8 +768,19 @@ You can add the key to `known_hosts` by running the following command: ssh-keyscan bitbucket.com >> ~/.ssh/known_hosts ``` -- +GitLab self-managed:: ++ +-- +For GitLab self-managed instances, you need to add the SSH host keys to a "known hosts" file (`~/.ssh/known_hosts`). This enables CircleCI to verify that the host it is connecting to is authentic. The **known_hosts** input stores your instance's public host keys so CircleCI jobs can verify the remote host's identity when checking out code. + +SSH keys for remote servers can be fetched by running `ssh-keyscan `, for example, `ssh-keyscan test-gitlab.circleci.com`. + +When retrieving the host keys, you can confirm that you have the correct key by checking its fingerprints. You can check the fingerprints found in the **Instance Configuration** section of your self-managed instance's Help pages (link:https://gitlab.com/help/instance_configuration#ssh-host-keys-fingerprints[this Instance Configuration page] shows an example). +-- ==== +#Do we need this step for people doing custom checkout for Bitbucket and GitLab.com?# + == Best practices for SSH keys NOTE: This section is relevant to projects in a `github` or `bitbucket` type organization. diff --git a/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc b/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc index 3f271b6747..cbd62d1767 100644 --- a/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc +++ b/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc @@ -88,7 +88,7 @@ NOTE: Only organization admins and project admins can delete projects. If you want to remove a project from your CircleCI account, follow the steps below. -CAUTION: Deleting a project will remove the complete build history. +CAUTION: Deleting a project will remove the complete build history. [tabs] ==== From dedee044a5f256d422024623f93c813dc81052a8 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Fri, 14 Nov 2025 16:14:28 +0000 Subject: [PATCH 13/23] fix table scroll and archive gitlab integration page --- .../integration/pages => archive}/gitlab-integration.adoc | 0 .../pages/users-organizations-and-integrations-guide.adoc | 5 ++++- 2 files changed, 4 insertions(+), 1 deletion(-) rename {docs/guides/modules/integration/pages => archive}/gitlab-integration.adoc (100%) diff --git a/docs/guides/modules/integration/pages/gitlab-integration.adoc b/archive/gitlab-integration.adoc similarity index 100% rename from docs/guides/modules/integration/pages/gitlab-integration.adoc rename to archive/gitlab-integration.adoc diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 35be418cd4..f81c809f1b 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -2,7 +2,7 @@ :page-platform: Cloud :page-description: A guide to understanding user accounts, organizations and integrations with version control systems in CircleCI. :experimental: -:page-aliases: guides:integration:github-apps-integration.adoc, guides:integration:github-integration.adoc, guides:integration:bitbucket-integration.adoc +:page-aliases: guides:integration:github-apps-integration.adoc, guides:integration:github-integration.adoc, guides:integration:bitbucket-integration.adoc, guides:integration:gitlab-integration.adoc 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. @@ -552,6 +552,8 @@ If you have a `bitbucket` organization you can have Bitbucket Cloud pipelines. The trigger options available to you depend on your pipeline type. These options are described in the following table: +[.table-scroll] +-- [options="header",cols="9*"] |=== |Pipeline type @@ -614,6 +616,7 @@ The trigger options available to you depend on your pipeline type. These options ^|[.circle-red]#*No*# ^|[.circle-green]#*Yes*# |=== +-- == How CircleCI checks out your code From db70de903dec801227b6333e4ff6d405d9f80690 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Mon, 17 Nov 2025 11:26:00 +0000 Subject: [PATCH 14/23] some minor fixes --- ...-organizations-and-integrations-guide.adoc | 25 +++++++++++-------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index f81c809f1b..ce4447ea65 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -71,9 +71,9 @@ Each organization has its own settings, including security, integrations, and re A CircleCI _organization_ can be one of three types: -A CircleCI `circleci` organization:: This organization type is created separately to any VCS connection between CircleCI and your code repositories. Within a `circleci` organization you create projects and then connect them to your code repositories. -A CircleCI `github` organization:: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. -A CircleCI `bitbucket` organization:: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account. Your Bitbucket repositories appear as projects that can be set up in CircleCI. +* `circleci`: This organization type is created separately to any VCS connection between CircleCI and your code repositories. Within a `circleci` organization you create projects and then connect them to your code repositories. +* `github`: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. +* `bitbucket`: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account. Your Bitbucket repositories appear as projects that can be set up in CircleCI. For full details on creating organizations, see the xref:getting-started:create-an-organization.adoc[Create an organization] page. @@ -81,6 +81,7 @@ The following organization settings are available: [.table-scroll] -- +.Organization settings [cols="1,2", options="header"] |=== | Organization settings section | What you will find here @@ -104,7 +105,7 @@ The following organization settings are available: | Orb security settings, you can choose to allow just certified orbs, all orbs, and choose to allow private orbs. Request audit logs and/or set up audit log streaming. | Policies -| Find a list of policis that have been created for your organization. +| Find a list of policies that have been created for your organization. | Advanced | Opt in/out of the following: intelligent summaries for build failures, image brownouts, triggering pipelines with unversioned config. @@ -122,7 +123,7 @@ The following organization settings are available: | `circleci` organizations only. Integration set up for GitLab self-managed and Bitbucket Data Center. | Singe sign-on -| `circleci` organizations on Scale Planonly. Set up SSO for your organization. +| `circleci` organizations on Scale Plan only. Set up SSO for your organization. |=== -- @@ -136,7 +137,7 @@ The following organization settings are available: -- For `github` and `bitbucket` type organizations projects are synonymous with repositories. Select "Projects" in the link:https://app.circleci.com/home[CircleCI web app] to view your repositories. From here you have the option to: -* Set up new repositories as CircleCI projects, which involves committing a CircleCI `config.yml` file to the repository to define your pipeline. THis creates a GitHub OAuth or Bitbucket Cloud pipeline for you, which you can view in menu:Project Settings[Project Setup] or menu:Project Settings[Pipelines] . +* 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 or Bitbucket Cloud pipeline for you, which you can view in menu:Project Settings[Project Setup] (GitHub) or menu:Project Settings[Pipelines] (Bitbucket). * 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: @@ -144,12 +145,13 @@ When you set up a project to build with CircleCI, the following settings are add - 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. +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. +* 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. @@ -175,6 +177,7 @@ The following project settings are available: [.table-scroll] -- +.Project settings [cols="1,2", options="header"] |=== | Project settings section | What you will find here @@ -203,7 +206,7 @@ a| Enable/disable various features for the project: * Disable SSH reruns. | Environment variables -| Add project environment variables. Youc an add individually or import from another project. You will find a list of project environment variables on this page. +| Add project environment variables. You can add individually or import from another project. You will find a list of project environment variables on this page. | SSH keys | Add deploy and user keys for `github` and `bitbucket` organizations. Add additional SSH keys for your project for all organization types. @@ -231,7 +234,7 @@ a| Enable/disable various features for the project: == Integration options -The integration options available to you depend on your organization type. By _integration type_ we mean the way CircleCI checks out your code from your VCS provider. Options are as follows: +The integration options available to you depend on your organization type. By _integration_ we mean the way CircleCI checks out your code from your VCS provider. Options are as follows: #TODO would it be right to say that if you can integrate with GL SaaS you can with self managed? Then we can simplify this to "GitLab" and then say that integration type is the same as pipeline type?# From c84892eec7070635af6ab75674bd5b3a5c6252ad Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Mon, 17 Nov 2025 12:38:39 +0000 Subject: [PATCH 15/23] add section for ebable project to checkout repos section --- .../about-circleci/pages/concepts.adoc | 2 +- .../deploy-to-azure-container-registry.adoc | 2 +- .../deploy/pages/set-up-rollbacks.adoc | 2 +- ...-organizations-and-integrations-guide.adoc | 28 ++++++++++++------- 4 files changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/guides/modules/about-circleci/pages/concepts.adoc b/docs/guides/modules/about-circleci/pages/concepts.adoc index 95ffde1fa1..9961db416e 100644 --- a/docs/guides/modules/about-circleci/pages/concepts.adoc +++ b/docs/guides/modules/about-circleci/pages/concepts.adoc @@ -552,7 +552,7 @@ See the xref:orchestrate:jobs-steps.adoc[Jobs and steps] page for more informati [#user-types] == User roles -CircleCI roles are set up differently depending on your xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organization-type[organization type]. +CircleCI roles are set up differently depending on your xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organizations[organization type]. include::ROOT:partial$tips/check-org-type.adoc[] diff --git a/docs/guides/modules/deploy/pages/deploy-to-azure-container-registry.adoc b/docs/guides/modules/deploy/pages/deploy-to-azure-container-registry.adoc index 257beab42a..c4e8e312d5 100644 --- a/docs/guides/modules/deploy/pages/deploy-to-azure-container-registry.adoc +++ b/docs/guides/modules/deploy/pages/deploy-to-azure-container-registry.adoc @@ -59,4 +59,4 @@ workflows: only: main # Only deploys when the commit is on the `main` branch ``` -If pushing to your repository is required, see the "Deployment Keys" section of the xref:integration:github-integration.adoc#deploy-keys-and-user-keys[GitHub] or xref:integration:bitbucket-integration.adoc#deploy-keys-and-user-keys[Bitbucket Cloud] instructions. Then, configure the Azure Web App to use your production branch. +If pushing to your repository is required, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#enable-project-to-check-out-additional-private-repositories[Users, Organizations, and Integrations Guide]. Then, configure the Azure Web App to use your production branch. diff --git a/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc b/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc index ab55b192a7..ad077f475b 100644 --- a/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc +++ b/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc @@ -59,7 +59,7 @@ image::guides:ROOT:deploy/project-overview-rollback.png[Rollback button on proje === 2. Confirm GitHub App installation -NOTE: To set up rollback pipelines, you must install the CircleCI GitHub App into your organization. For more information, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#install-the-circleci-github-app[Users, organizations, and integrations guide]. +NOTE: To set up rollback pipelines, you must install the CircleCI GitHub App into your organization. For more information, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#integration-options[Users, organizations, and integrations guide]. - If the GitHub App is not installed in your organization, the guided setup process prompts you to install it. + diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index ce4447ea65..30e002487f 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -799,14 +799,14 @@ This section describes best practices for using SSH keys in your CircleCI pipeli * You must rotate the Deploy or User key as part of revoking user access to that repository. See the xref:security:rotate-project-ssh-keys.adoc[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-github-user-key] -== Create a GitHub user key +[#create-a-user-key] +== Create a user key -NOTE: If your organization is a `github` or `bitbucket` type organization, you can create a GitHub user key. +NOTE: If your organization is a `github` or `bitbucket` type organization, you can create a user key for your project. -Create a GitHub user key in CircleCI when you need write access to your GitHub repositories during your CI/CD pipeline, or when you need to access multiple repositories that your user account has access to. +Create a user key in CircleCI when you need write access to your GitHub or Bitbucket repositories during your CI/CD pipeline, or when you need to access multiple repositories that your user account has access to. -Some example tasks where you might need a GitHub user key: +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 (like updating a changelog, bumping version numbers, generating documentation, or creating automated pull requests) you need write permissions that a user key provides. * 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. This is useful for: @@ -826,16 +826,16 @@ The trade-off with chosing a user key is that user keys grant broad access based We recommend creating a dedicated "machine user" GitHub/Bitbucket account with minimal necessary permissions, then adding that account's user key to CircleCI, rather than using your personal GitHub/Bitbucket account's key. -To create a GitHub user key, follow these steps: +To create a user key, follow these steps: NOTE: To use the recommended approach of creating a machine user, you will need to create a new GitHub/Bitbucket account with minimal necessary permissions and then follow these steps logged in as that machine user account. include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[] . In the sidebar menu, select *SSH Keys*. -. Under the **User Key** section, select btn:[Authorize With GitHub]. The page will refresh while the authorization takes place and you will be redirected back to the project settings overview page. -. Navigate back to **SSH keys** and go to the **User Key** section. -. Select btn:[Add User Key], then btn:[Confirm User]. You will now see your user key displayed on the page. +. Under the **User Key** section, select btn:[Add User Key]. +. You will see a warning that you should use a machine user. Select btn:[Confirm User]. +. You will now see your user key displayed on the page. [#user-key-security] === User key security @@ -1125,4 +1125,12 @@ For guidance on deleting your user account link:https://support.circleci.com/hc/ See the xref:security:delete-organizations-and-projects.adoc[Delete organizations and projects] page for full instructions. -#TO DO explain the different between deleting an OAuth org and disconnecting from user settings# \ No newline at end of file +#TO DO explain the different between deleting an OAuth org and disconnecting from user settings# + +[#enable-project-to-check-out-additional-private-repositories] +=== 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 <> 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 <> section of this page for instructions. + From 8c68399d8f12f8a63eb8595cefb917e42a390b9d Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Mon, 17 Nov 2025 14:54:27 +0000 Subject: [PATCH 16/23] fix links --- .../partials/faq/cancel-subscription-faq-snip.adoc | 2 +- .../guides/modules/integration/pages/add-ssh-key.adoc | 2 +- docs/guides/modules/integration/pages/oss.adoc | 2 +- .../version-control-system-integration-overview.adoc | 4 ++-- docs/guides/modules/orchestrate/pages/pipelines.adoc | 4 ++-- .../users-organizations-and-integrations-guide.adoc | 11 ++++++----- .../security/pages/rotate-project-ssh-keys.adoc | 2 +- .../modules/ROOT/pages/configuration-reference.adoc | 2 +- 8 files changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/guides/modules/ROOT/partials/faq/cancel-subscription-faq-snip.adoc b/docs/guides/modules/ROOT/partials/faq/cancel-subscription-faq-snip.adoc index 0f6f608afa..7612d26561 100644 --- a/docs/guides/modules/ROOT/partials/faq/cancel-subscription-faq-snip.adoc +++ b/docs/guides/modules/ROOT/partials/faq/cancel-subscription-faq-snip.adoc @@ -16,7 +16,7 @@ For GitHub users, your account has the "Owner" role in your GitHub organization. For Bitbucket Cloud users, your account has "Admin" permissions in your Bitbucket repository. -For GitLab users, your account is listed as "Org Admin" in the CircleCI web app under xref:guides:integration:gitlab-integration.adoc#organization-settings-people[**Organization Settings > People**]. +For GitLab users, your account is listed as "Org Admin" in the CircleCI web app under menu:Organization Settings[People]. [#what-happens-upon-cancelling-a-performance-plan-subscription] === What happens upon cancelling a Performance Plan subscription? diff --git a/docs/guides/modules/integration/pages/add-ssh-key.adoc b/docs/guides/modules/integration/pages/add-ssh-key.adoc index c05dfb6d94..3b9c422115 100644 --- a/docs/guides/modules/integration/pages/add-ssh-key.adoc +++ b/docs/guides/modules/integration/pages/add-ssh-key.adoc @@ -5,7 +5,7 @@ Add additional SSH keys to your project for access to deploy to other services or to write to, or checkout code from other repositories. -If you want to set up an SSH key in order to checkout code from additional repositories in GitHub (xref:github-integration.adoc[GitHub OAuth app only]) or Bitbucket Cloud within a job, refer to the xref:github-integration.adoc#enable-your-project-to-check-out-additional-private-repositories[GitHub OAuth app] or xref:bitbucket-integration.adoc#enable-your-project-to-check-out-additional-private-repositories[Bitbucket Cloud] integration pages. If you need additional SSH keys to access other services and your org is set up to the use xref:github-integration.adoc[GitHub OAuth app] or Bitbucket Cloud, follow the steps below. +TIP: If you want to set up an SSH key in order to checkout code from additional repositories in GitHub or Bitbucket Cloud and and you have a `github` or `bitbucket` organization, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#create-a-user-key[Users, Organizations, and Integrations Guide] for steps to add a user key. Alternatively follow steps on this page to add additional SSH keys to your project. You may need to add the public key to `~/.ssh/authorized_keys` in order to add SSH keys. diff --git a/docs/guides/modules/integration/pages/oss.adoc b/docs/guides/modules/integration/pages/oss.adoc index 2a4ab5a28f..9893628daa 100644 --- a/docs/guides/modules/integration/pages/oss.adoc +++ b/docs/guides/modules/integration/pages/oss.adoc @@ -111,7 +111,7 @@ Running an unrestricted build in a parent repository can be dangerous. Projects By default, CircleCI does not pass secrets to builds from forked PRs for open source projects and hides four types of configuration data: * <> set through the application. -* xref:github-integration.adoc#deploy-keys-and-user-keys[Deployment keys and user keys]. +* xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#create-a-user-key[Deployment keys and user keys]. * Passphraseless private SSH keys you have xref:add-ssh-key.adoc[added to CircleCI] to access arbitrary hosts during a build. * xref:deploy:deploy-to-aws.adoc[AWS permissions] and configuration files. diff --git a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc index daf9236d68..e5d0c6ebda 100644 --- a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc +++ b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc @@ -97,7 +97,7 @@ include::ROOT:partial$tips/check-github-type.adoc[Check your GitHub integration ^1^ _Possible using xref:orchestrate:dynamic-config.adoc[dynamic configuration]._ -^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:github-integration.adoc#using-github-app-functionality[here]._ +^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:using-the-github-app-in-an-oauth-org.adoc[here]._ ^3^ _When GitHub Checks are enabled we automatically disable GitHub status updates to avoid duplication of statuses. You can manage GitHub status updates via project settings._ @@ -170,7 +170,7 @@ include::ROOT:partial$tips/check-github-type.adoc[Check your GitHub integration ^1^ _One alternative is to use a xref:orchestrate:custom-webhooks.adoc[custom webhook] to generate a URL that you `curl` with a 3rd party scheduling tool._ -^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:github-integration.adoc#using-github-app-functionality[here]._ +^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:using-the-github-app-in-an-oauth-org.adoc[here]._ ^3^ _For GitLab Cloud and GitLab self-managed projects, you can choose to trigger pipelines upon the creation of merge requests, by selecting the *Only Build Merge Requests* trigger filter._ diff --git a/docs/guides/modules/orchestrate/pages/pipelines.adoc b/docs/guides/modules/orchestrate/pages/pipelines.adoc index 36ff96a34f..8437048a17 100644 --- a/docs/guides/modules/orchestrate/pages/pipelines.adoc +++ b/docs/guides/modules/orchestrate/pages/pipelines.adoc @@ -100,9 +100,9 @@ To add or edit a pipeline, follow these steps: ** Give your pipeline a descriptive name, for example `Run tests and deploy`. ** Under Integration select the platform that matches where your project is set up (for example, GitHub App). + -NOTE: If you integrate with xref:integration:github-integration.adoc[CircleCI's GitHub OAuth App] you can select GitHub App here to install the App into your org and access xref:integration:github-integration.adoc#using-github-app-functionality[improved security and new features]. This is a one-time step, which can be done by an organization admin or a user who has admin access to at least one repository in the organization. Once installed, further GitHub App pipelines can be setup without this installation step. +NOTE: If you integrate with xref:integration:github-integration.adoc[CircleCI's GitHub OAuth App] you can select GitHub App here to install the App into your org and access xref:integration:using-the-github-app-in-an-oauth-org.adoc[improved security and new features]. This is a one-time step, which can be done by an organization admin or a user who has admin access to at least one repository in the organization. Once installed, further GitHub App pipelines can be setup without this installation step. + -NOTE: For GitLab self-managed, you can input any instance that you have previously set up in CircleCI. If you wish to set a different feature branch or repository from a self-managed instance as a new pipeline, you will first need to add a new connection via your xref:integration:gitlab-integration.adoc#organization-settings-integrations[menu:Organization Settings[Integrations]]. In either case, you will also need to enter your personal access token again to authorize this connection. +NOTE: For GitLab self-managed, you can input any instance that you have previously set up in CircleCI. If you wish to set a different feature branch or repository from a self-managed instance as a new pipeline, you will first need to add a new connection via your xref:integration:users-organizations-and-integrations-guide.adoc#gitlab-self-managed-integration-setup[menu:Organization Settings[Integrations]]. In either case, you will also need to enter your personal access token again to authorize this connection. ** Authorize your connection if this is not already showing with a check mark image:guides:ROOT:icons/passed.svg[passed icon, role="no-border"]. ** Define where the config file for this pipeline is stored: *** Select a repository from the dropdown. diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 30e002487f..83f19a8354 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -19,6 +19,7 @@ You can log in to CircleCI using one of the following methods: Select your icon in the top bar and select **User settings** to access the following: +[#user-settings] [.table-scroll] -- .User settings @@ -311,11 +312,11 @@ Once you have integrated your CircleCI organization with your GitLab self-manage + image::guides:ROOT:gl-sm-integrations.png[Add a new self-managed instance on the Integrations page] -. You will need to enter the instance URL, as described in the xref:#sign-up[Sign up] section above. +. You will need to enter the instance URL. NOTE: The ability to edit or delete existing integrations is not currently supported. -For GitLab.com, account integrations can be managed under your xref:#user-account-integrations[user settings]. +For GitLab.com, account integrations can be managed under your <>. NOTE: If you are using both CircleCI's Bitbucket Data Center and GitLab self-managed integrations, there is a known bug in the menu:Organization Settings[Integrations] section of the CircleCI web app. Adding a `known_hosts` to one integration will populate the `known_hosts` for the other integration. To use both Bitbucket Data Center and GitLab self-managed integrations within the same CircleCI organization, add both respective `known_hosts` values to the one input field separated by a new line. @@ -665,7 +666,7 @@ When CircleCI builds your project, the private key is installed into the `.ssh` - Checking out any GitHub-hosted private dependencies - Automatic git merging/tagging/etc -Private keys are also used to enable your project to <<#enable-your-project-to-check-out-additional-private-repositories,check out additional private repositories>>. +Private keys are also used to enable your project to check out additional private repositories. -- Bitbucket Cloud:: + @@ -691,7 +692,7 @@ When CircleCI builds your project, the private key is installed into the `.ssh` - Checking out any Bitbucket-hosted private dependencies - Automatic git merging/tagging/etc -Private keys are also used to enable your project to <<#enable-your-project-to-check-out-additional-private-repositories,check out additional private repositories>>. +Private keys are also used to enable your project to check out additional private repositories. -- GitLab:: + @@ -1021,7 +1022,7 @@ The following steps guide you through migrating you organization as follows: [CAUTION] ==== * You can not currently automate migrating your organization from the GitHub OAuth app to CircleCI's GitHub App integration. -* Before proceeding, confirm that you do not immediately need any of the functionality listed in the <> section below. +* Before proceeding, confirm that you do not immediately need any of the functionality that is currently unsupported for GitHub App pipelines. For a matrix of feature support see the xref:integration:version-control-system-integration-overview.adoc[Version Control System Integration Overview] page. * The following steps include *creating a new org*. If you need to transfer private orbs or self-hosted runner resource classes to your new org, contact link:https://support.circleci.com/[Support at CircleCI] before following step 14. * If you have a dedicated account team at CircleCI, contact them first to discuss your migration. ==== diff --git a/docs/guides/modules/security/pages/rotate-project-ssh-keys.adoc b/docs/guides/modules/security/pages/rotate-project-ssh-keys.adoc index 590b486c78..55f934afd1 100644 --- a/docs/guides/modules/security/pages/rotate-project-ssh-keys.adoc +++ b/docs/guides/modules/security/pages/rotate-project-ssh-keys.adoc @@ -71,7 +71,7 @@ Go to **Project Settings > SSH Keys** to view SSH keys set up for your project. . Take note of the current key information to rotate. . Delete the user key by clicking the **X**. -. Add a new user key following the xref:integration:bitbucket-integration.adoc#create-a-bitbucket-user-key[Create a Bitbucket user key] instructions. +. Add a new user key following the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#create-a-user-key[Create a user key] instructions. . Go to Bitbucket’s user account settings to delete the matching public key. The Bitbucket URL is typically `https://bitbucket.org/account/settings/ssh-keys/`. The user names the keys, therefore, CircleCI does not know if the key name contains the string `CircleCI`. It is recommended to remove any key created before the rotation. [#rotate-an-additional-SSH-key-bitbucket] diff --git a/docs/reference/modules/ROOT/pages/configuration-reference.adoc b/docs/reference/modules/ROOT/pages/configuration-reference.adoc index c605e1088c..3f5070ce9a 100644 --- a/docs/reference/modules/ROOT/pages/configuration-reference.adoc +++ b/docs/reference/modules/ROOT/pages/configuration-reference.adoc @@ -2260,7 +2260,7 @@ NOTE: The lifetime of artifacts, workspaces, and caches can be customized on the [#add-ssh-keys] === *`add_ssh_keys`* -Special step that adds SSH keys from a project's settings to a container. Also configures SSH to use these keys. For more information on SSH keys see the xref:guides:integration:github-integration.adoc#create-additional-github-ssh-keys[Create additional GitHub SSH keys] page. +Special step that adds SSH keys from a project's settings to a container. Also configures SSH to use these keys. For more information on SSH keys see the xref:guides:integration:add-ssh-key.adoc[Add Additional SSH keys] page. CAUTION: *Using server?* only MD5 fingerprints are supported. In CircleCI in menu:Project Settings[SSH keys > Additional SSH keys] the MD5 fingerprint will be visible. SHA256 support is planned for an upcoming server release. From f5278940d620db79809c893b1f124be1b686f017 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Mon, 17 Nov 2025 15:00:26 +0000 Subject: [PATCH 17/23] fix links again --- .../pages/version-control-system-integration-overview.adoc | 4 ++-- docs/guides/modules/orchestrate/pages/pipelines.adoc | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc index e5d0c6ebda..92ee1d88f3 100644 --- a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc +++ b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc @@ -97,7 +97,7 @@ include::ROOT:partial$tips/check-github-type.adoc[Check your GitHub integration ^1^ _Possible using xref:orchestrate:dynamic-config.adoc[dynamic configuration]._ -^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:using-the-github-app-in-an-oauth-org.adoc[here]._ +^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:using-the-circleci-github-app-in-an-oauth-org.adoc[here]._ ^3^ _When GitHub Checks are enabled we automatically disable GitHub status updates to avoid duplication of statuses. You can manage GitHub status updates via project settings._ @@ -170,7 +170,7 @@ include::ROOT:partial$tips/check-github-type.adoc[Check your GitHub integration ^1^ _One alternative is to use a xref:orchestrate:custom-webhooks.adoc[custom webhook] to generate a URL that you `curl` with a 3rd party scheduling tool._ -^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:using-the-github-app-in-an-oauth-org.adoc[here]._ +^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:using-the-circleci-github-app-in-an-oauth-org.adoc[here]._ ^3^ _For GitLab Cloud and GitLab self-managed projects, you can choose to trigger pipelines upon the creation of merge requests, by selecting the *Only Build Merge Requests* trigger filter._ diff --git a/docs/guides/modules/orchestrate/pages/pipelines.adoc b/docs/guides/modules/orchestrate/pages/pipelines.adoc index 8437048a17..1260210e35 100644 --- a/docs/guides/modules/orchestrate/pages/pipelines.adoc +++ b/docs/guides/modules/orchestrate/pages/pipelines.adoc @@ -100,9 +100,9 @@ To add or edit a pipeline, follow these steps: ** Give your pipeline a descriptive name, for example `Run tests and deploy`. ** Under Integration select the platform that matches where your project is set up (for example, GitHub App). + -NOTE: If you integrate with xref:integration:github-integration.adoc[CircleCI's GitHub OAuth App] you can select GitHub App here to install the App into your org and access xref:integration:using-the-github-app-in-an-oauth-org.adoc[improved security and new features]. This is a one-time step, which can be done by an organization admin or a user who has admin access to at least one repository in the organization. Once installed, further GitHub App pipelines can be setup without this installation step. +NOTE: If you integrate with xref:integration:github-integration.adoc[CircleCI's GitHub OAuth App] you can select GitHub App here to install the App into your org and access xref:integration:using-the-circleci-github-app-in-an-oauth-org.adoc[improved security and new features]. This is a one-time step, which can be done by an organization admin or a user who has admin access to at least one repository in the organization. Once installed, further GitHub App pipelines can be setup without this installation step. + -NOTE: For GitLab self-managed, you can input any instance that you have previously set up in CircleCI. If you wish to set a different feature branch or repository from a self-managed instance as a new pipeline, you will first need to add a new connection via your xref:integration:users-organizations-and-integrations-guide.adoc#gitlab-self-managed-integration-setup[menu:Organization Settings[Integrations]]. In either case, you will also need to enter your personal access token again to authorize this connection. +NOTE: For GitLab self-managed, you can input any instance that you have previously set up in CircleCI. If you wish to set a different feature branch or repository from a self-managed instance as a new pipeline, you will first need to add a new connection via your xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#gitlab-self-managed-integration-setup[menu:Organization Settings[Integrations]]. In either case, you will also need to enter your personal access token again to authorize this connection. ** Authorize your connection if this is not already showing with a check mark image:guides:ROOT:icons/passed.svg[passed icon, role="no-border"]. ** Define where the config file for this pipeline is stored: *** Select a repository from the dropdown. From 65ffb9f2d729bc305e87c0fefbdb02a7edcadf0b Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Tue, 18 Nov 2025 12:40:35 +0000 Subject: [PATCH 18/23] streamline integration instructions for self-hosted VCS --- .../getting-started/pages/create-project.adoc | 37 ++++-- .../modules/orchestrate/pages/pipelines.adoc | 17 +++ .../orchestrate/pages/set-up-triggers.adoc | 24 +++- ...-organizations-and-integrations-guide.adoc | 121 ++++++------------ 4 files changed, 99 insertions(+), 100 deletions(-) diff --git a/docs/guides/modules/getting-started/pages/create-project.adoc b/docs/guides/modules/getting-started/pages/create-project.adoc index e9f84b7f6b..b86c6c4405 100644 --- a/docs/guides/modules/getting-started/pages/create-project.adoc +++ b/docs/guides/modules/getting-started/pages/create-project.adoc @@ -110,6 +110,7 @@ image::guides:ROOT:create-project/download-config-file.png[Modal showing options GitLab self-managed:: + -- +CAUTION: Before creating a project that you want to integrate with code in a GitLab self-managed instance, you need to set up an integration with your GitLab self-managed instance. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#integration-options[GitLab self-managed integration setup] page for more information. NOTE: **Remove GitLab CI/CD config** You should remove the `.gitlab-ci.yml` file from projects you integrate with CircleCI. This prevents you from having CI/CD builds happening in both systems. There is an option to _disable_ GitLab CI/CD for a project in the GitLab UI but using this is **not recommended**. @@ -117,11 +118,13 @@ Follow these steps to create a new project in CircleCI: include::ROOT:partial$create-project/steps-up-to-pipeline.adoc[Insert steps from selecting Create project up to setting up a pipeline] -. Choose a repo to connect to your project. If you do not see your repo listed, select btn:[Add] or btn:[Connect to GitLab self-managed] to access repositories from your GitLab self-managed instance. Select btn:[GitLab self-managed] and then btn:[Authorize in GitLab self-managed] +. Choose a repo to connect to your project. If you do not see your repo listed, select btn:[Add] to access repositories from your GitLab self-managed instance. + .Choose a repo to connect your code to your project image::guides:ROOT:create-project/choose-a-repo-gitlab.png[Choose a repository window with option to add another VCS] + +Select btn:[GitLab self-managed] and then btn:[Authorize in GitLab self-managed] ++ .Authorize GitLab self-managed image::guides:ROOT:create-project/authorize-gitlab-self-managed.png[Option to authorize a new VCS integration] @@ -131,16 +134,14 @@ image::guides:ROOT:create-project/authorize-gitlab-self-managed.png[Option to au image::guides:ROOT:create-project/create-new-gitlab-self-managed-project.png[Create new project window] + **** -If this is your first GitLab self-managed project you will now set up your integration: - -* Verify your GitLab URL. The field will automatically append `/api/v4`, so the URL that CircleCI uses to connect to your account looks something like `https://test-gitlab.circleci.com/api/v4`. -* Generate an add a personal access token -* Add your known hosts, following the instructions in the app +If you set up your GitLab self-managed instance you should see your instance URL and known_hosts. If not see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#integration-options[integration instructions]. **** +* Generate and add a personal access token with the `api` scope. -** Use the repository dropdown menu to tell CircleCI where your code is stored. -** Select **Create Project**. You will then be redirected to the Pipelines page. -** The express CircleCI configuration setup is not currently available for GitLab self-managed projects. You will need to add a `.circleci/config.yml` file in your repository if it has not yet been set up. If the repository you selected already contains a `.circleci/config.yml`, push a commit to see your pipeline on the dashboard. +** Use the Repository dropdown menu to tell CircleCI where your code is stored. +** Use the Branch dropdown to tell CircleCI which branch to use for your pipeline. +** Select **Save**. You will then be redirected to the Pipelines page. +** The express CircleCI configuration setup is not currently available for GitLab self-managed projects. You will need to add a `.circleci/config.yml` file in your repository. If the repository you selected already contains a `.circleci/config.yml`, push a commit to see your pipeline on the dashboard. + **** For guidance on creating a `config.yml` file, see the following pages: @@ -153,19 +154,27 @@ For guidance on creating a `config.yml` file, see the following pages: Bitbucket Data Center:: + -- +CAUTION: Before creating a project that you want to integrate with code in a Bitbucket Data Center instance, you need to set up an integration with your Bitbucket Data Center instance. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#integration-options[Bitbucket Data Center integration setup] page for more information. + Follow these steps to create a new project in CircleCI: include::ROOT:partial$create-project/steps-up-to-pipeline.adoc[Insert steps from selecting Create project up to setting up a pipeline] -. Choose a repo to connect to your project. If you do not see your repo listed, select btn:[Add] to access repositories from GitHub. Select btn:[Bitbucket Data Center] and then btn:[Authorize in Bitbucket Data Center] +. Choose a repo to connect to your project. If you do not see your repo listed, select btn:[Add]. Select btn:[Bitbucket Data Center] and then btn:[Authorize in Bitbucket Data Center] + .Access Bitbucket data center repos image::guides:ROOT:create-project/authorize-bitbucket-data-center.png[Choose a repository window with option to add another VCS] -. Next, follow the steps on the xref:integration:bitbucket-data-center-integration.adoc#integrate-a-project-with-circleci[Bitbucket integration setup] page to set up the following: -** An integration with your Bitbucket Data Center instance (if not already set up for your org). -** Set up a pipeline and trigger for your project. -** Add a configuration file to your repo. +. To set up your project 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 link:https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html[Bitbucket docs]. Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI. ++ +**** +If you set up your Bitbucket Data Center instance you should see your instance URL and known_hosts. If not see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#integration-options[integration instructions]. +**** + +** Use the repository dropdown menu to tell CircleCI where your code is stored. +** Use the Branch dropdown to tell CircleCI which branch to use for your pipeline. +** Select **Save**. You will then be redirected to the Pipelines page. +** The express CircleCI configuration setup is not currently available for Bitbucket Data Center projects. You will need to add a `.circleci/config.yml` file in your repository. If the repository you selected already contains a `.circleci/config.yml`, push a commit to see your pipeline on the dashboard. -- ==== diff --git a/docs/guides/modules/orchestrate/pages/pipelines.adoc b/docs/guides/modules/orchestrate/pages/pipelines.adoc index 1260210e35..dbc3203c89 100644 --- a/docs/guides/modules/orchestrate/pages/pipelines.adoc +++ b/docs/guides/modules/orchestrate/pages/pipelines.adoc @@ -112,6 +112,23 @@ NOTE: For GitLab self-managed, you can input any instance that you have previous Once you have set up a pipeline you need to set up a trigger to connect it to. Setting up a trigger is described in the following section. -- +Bitbucket Data Center:: ++ +-- +To add or edit a pipeline, follow these steps: + +. In the CircleCI web app, select **Projects** in the sidebar. +. Select the ellipsis next to your project image:guides:ROOT:icons/more.svg[more icon, role="no-border"] and choose **Project Settings**. +. Select **Pipelines** in the sidebar. +. Select btn:[Add Pipeline], or, if you wish to edit an existing pipeline select the pencil icon on the right. +. Complete the form fields and options: +** Give your pipeline a descriptive name, for example `Run tests and deploy`. +** Under Integration select the platform that matches where your project is set up (for example, Bitbucket Data Center). +** Authorize your connection if this is not already showing with a check mark image:guides:ROOT:icons/passed.svg[passed icon, role="no-border"]. +** Define where the config file for this pipeline is stored: +*** Select a repository from the dropdown. +*** Enter the path to the config file. +-- ==== == Pipeline states diff --git a/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc b/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc index fc2547e3b9..62d4c68e2c 100644 --- a/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc +++ b/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc @@ -100,7 +100,29 @@ To verify your trigger is set up correctly, trigger an event from your repositor Bitbucket Data Center:: + -- -For steps to add a trigger for a pipeline using Bitbucket Data Center, see the xref:integration:bitbucket-data-center-integration.adoc[Bitbucket Data Center] page. +To add a trigger for a pipeline, follow these steps: +. In the CircleCI web app, select **Projects** in the sidebar. +. Select the ellipsis next to your project image:guides:ROOT:icons/more.svg[more icon, role="no-border"] and choose **Project Settings**. +. Select **Triggers** in the sidebar. +. Select btn:[Add Trigger]. +. Select the same location in the "Connect to" dropdown menu that you selected for your pipeline (for example, Bitbucket Data Center). +. Select btn:[Next]. +. Complete the form fields and options: +** Give your trigger a descriptive name. +** Authorize your connection if this is not already showing with a check mark image:guides:ROOT:icons/passed.svg[passed icon, role="no-border"] (Not required for custom webhooks). +** Provide the project HTTP access token you created above. Select btn:[Connect]. +** Select the Trigger source repository +. If you have not already done so, **create a `.circleci` directory to the root of your repository, then add a `config.yml` file in that directory**. When you commit this change in your repository, you should see the pipeline trigger for the first time on the CircleCI dashboard. ++ +**** +For help with creating a CircleCI `config.yml`, see the following pages: + +* xref:getting-started:hello-world.adoc[Hello world] +* xref:toolkit:sample-config.adoc[Sample config] +* xref:reference:ROOT:configuration-reference.adoc[Configuration reference] +**** + +Each time you push changes to your Bitbucket Data Center repository, a new pipeline is triggered and you should see it running for the project within the CircleCI web app. -- Scheduled:: + diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 83f19a8354..8c20286d17 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -278,22 +278,28 @@ Integrations are set up as follows: * GitHub OAuth and Bitbucket Cloud are set up when logging in to CircleCI with your GitHub or Bitbucket social login. * GitLab self-managed and Bitbucket Data Center are set up from menu:Organization Settings[Integrations]. -=== GitLab self-managed integration setup +NOTE: If you are using both CircleCI's Bitbucket Data Center and GitLab self-managed integrations, there is a known bug in the menu:Organization Settings[Integrations] section of the CircleCI web app. Adding a `known_hosts` to one integration will populate the `known_hosts` for the other integration. To use both Bitbucket Data Center and GitLab self-managed integrations within the same CircleCI organization, add both respective `known_hosts` values to the one input field separated by a new line. -You will set up an integration with your GitLab self-managed instance when creating a project. You will need: +#TODO Add screenshots for these setup sections# -* Your GitLab self-managed instance URL, for example, `https://test-gitlab.circleci.com`. +[tabs] +==== +GitLab self-managed integration setup:: + -Your self-managed instance must already contain at least one GitLab project. The authorization attempt will be unsuccessful if your instance does not have any projects. Note that the self-managed instance must be accessible via the public internet. If the self-managed instance is behind a firewall, see link:https://discuss.circleci.com/t/gitlab-self-managed-support-on-circleci-is-now-here/47726/3?u=sebastian-lerner[a suggested workaround]. +-- +Set up an integration with your GitLab self-managed instance from menu:Organization Settings[Integrations] as follows: -* A link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html[personal access token]. This token must have the `api` scope. +. Select btn:[Set Up Integration] next to GitLab self-managed. +. Enter your GitLab self-managed instance URL, for example, `https://test-gitlab.circleci.com`. ++ +Your self-managed instance must already contain at least one GitLab project. The authorization attempt will be unsuccessful if your instance does not have any projects. Note that the self-managed instance must be accessible via the public internet. If the self-managed instance is behind a firewall, see link:https://discuss.circleci.com/t/gitlab-self-managed-support-on-circleci-is-now-here/47726/3?u=sebastian-lerner[a suggested workaround]. -[#known-hosts-input] -* 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. +. 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 should look something like: + -```shell +[,shell] +---- ➜ ~ ssh-keyscan test-gitlab.circleci.com # gitlab.com:22 SSH-2.0-GitLab-SSHD @@ -304,105 +310,50 @@ gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAA gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf # gitlab.com:22 SSH-2.0-GitLab-SSHD # gitlab.com:22 SSH-2.0-GitLab-SSHD -``` - -Once you have integrated your CircleCI organization with your GitLab self-managed instance, you will be able to see the integration in menu:Organization Settings[Integrations]. From here you can add integrations to other GitLab self-managed instances you have access to, as follows: +---- -. Navigate to menu:Organization Settings[Integrations] to add a new instance. -+ -image::guides:ROOT:gl-sm-integrations.png[Add a new self-managed instance on the Integrations page] +. Select btn:[Set Up Integration]. -. You will need to enter the instance URL. +To create pipelines for your code in GitLab self-managed, you will need to generate a link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html[personal access token]. This token must have the `api` scope. -NOTE: The ability to edit or delete existing integrations is not currently supported. +You cannot currently edit or delete existing GitLab self-managed integrations. For GitLab.com, account integrations can be managed under your <>. - -NOTE: If you are using both CircleCI's Bitbucket Data Center and GitLab self-managed integrations, there is a known bug in the menu:Organization Settings[Integrations] section of the CircleCI web app. Adding a `known_hosts` to one integration will populate the `known_hosts` for the other integration. To use both Bitbucket Data Center and GitLab self-managed integrations within the same CircleCI organization, add both respective `known_hosts` values to the one input field separated by a new line. - -=== Bitbucket Data Center integration setup - -. **Set up your integration with Bitbucket Data Center if you have not already**: -.. In the CircleCI web app, select **Organization Settings** in the sidebar. -.. Select **Integrations** in the sidebar. -.. Select btn:[Set Up Integration] next to Bitbucket Data Center. -.. In the modal, enter your Bitbucket Data Center instance URL and your known_hosts. For guidance on generating known_hosts, see <>. +-- +Bitbucket Data Center integration setup:: + -NOTE: If you are using both CircleCI's Bitbucket Data Center and GitLab self-managed integrations, there is a known bug in the menu:Organization Settings[Integrations] section of the CircleCI web app. Adding a `known_hosts` to one integration will populate the `known_hosts` for the other integration. To use both Bitbucket Data Center and GitLab self-managed integrations within the same CircleCI organization, add both respective `known_hosts` values to the one input field separated by a new line. +-- +Set up an integration with your Bitbucket Data Center instance from menu:Organization Settings[Integrations] as follows: -.. Select btn:[Set Up Integration]. -.. Select the back arrow to exit **Organization Settings**. - -. For the next sections 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 link:https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html[Bitbucket docs]. Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI. - -. **Set up a pipeline**: -.. Select **Project Settings**. -.. Select **Pipelines** in the sidebar. -.. Select **Set Up Pipeline**. Fill in the required fields: -** Give your pipeline a descriptive name. -** Select **Bitbucket Data Center** under Integration. -** Provide the project HTTP access token you created in the previous step. Select btn:[Connect]. -** Under Config, define where the config file for this pipeline is stored: -*** Select a repository from the dropdown. -*** Enter the path to the config file. Typically this is `.circleci/config.yml` but can be any file path with extension `*.yml`. -** Under Build Assets, select a checkout source for this pipeline. This is the repository that will be checked out when a link:https://circleci.com/docs/configuration-reference/#checkout[checkout step] is run. If your config is stored in the same repository as your code, pick the same repository you selected under Config Source. -.. Select btn:[Save]. - -. **Set up a trigger**: -.. Select **Triggers** in the Project Settings sidebar. -.. Select **Add Trigger**. -.. Select Bitbucket Data Center from the dropdown and select btn:[Next]. -.. Fill in the required fields: -** Give your trigger a descriptive name. -** Provide the project HTTP access token you created above. Select btn:[Connect]. -** Select the Trigger source repository -** Choose the pipeline you created in the previous step under the dropdown to show CircleCI which pipeline to trigger. -** If prompted, enter a config branch. This is the name of the branch that should be used to fetch your config file when a pipeline is triggered. This field is only required if your config is stored in a repository that is not the source of your trigger. -** If prompted, enter a checkout branch. This is the name of the branch that should be used to check out your code when a link:https://circleci.com/docs/configuration-reference/#checkout[checkout step] is run. This field is only required if the Checkout Source repository you configured in your Pipeline is not the source of your trigger. - -.. Select btn:[Save]. - -. If you have not already done so, **create a `.circleci` directory to the root of your repository, then add a `config.yml` file in that directory**. When you commit this change in your repository, you should see the pipeline trigger for the first time on the CircleCI dashboard. +. Select btn:[Set up integration] next to Bitbucket Data Center. +. In the modal enter your Bitbucket Data Center instance URL and your `known_hosts`: + -**** -For help with creating a CircleCI `config.yml`, see the following pages: - -* xref:getting-started:hello-world.adoc[Hello world] -* xref:toolkit:sample-config.adoc[Sample config] -* xref:reference:ROOT:configuration-reference.adoc[Configuration reference] -**** - -Each time you push changes to your Bitbucket Data Center repository, a new pipeline is triggered and you should see it running for the project within the CircleCI web app. - -image::guides:ROOT:gl-ga/gitlab-ga-successful-pipeline.png[Successful pipeline run] - -Make any further changes to your CircleCI config in your Bitbucket Data Center repository. Editing an existing CircleCI configuration within the web app is not currently available. - -Committing changes in your repository will automatically trigger a pipeline. Manually triggering a pipeline from the CircleCI web app is not available at this time. - -[#known-hosts] -=== Generate `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: - ++ TIP: 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 menu:Organization Settings[Integrations]. +. Select btn:[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 link:https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html[Bitbucket docs]. Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI. +-- +==== + == Limitations The following limits are currently in place for the Free Plan: From 54b5af6a9054424e7b412b0041bf90c9d87d59ff Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Tue, 18 Nov 2025 13:01:25 +0000 Subject: [PATCH 19/23] archive bbdc integraiton guides --- .../bitbucket-data-center-integration.adoc | 0 docs/guides/modules/ROOT/nav.adoc | 2 -- ...users-organizations-and-integrations-guide.adoc | 14 +++++++++----- 3 files changed, 9 insertions(+), 7 deletions(-) rename {docs/guides/modules/integration/pages => archive}/bitbucket-data-center-integration.adoc (100%) diff --git a/docs/guides/modules/integration/pages/bitbucket-data-center-integration.adoc b/archive/bitbucket-data-center-integration.adoc similarity index 100% rename from docs/guides/modules/integration/pages/bitbucket-data-center-integration.adoc rename to archive/bitbucket-data-center-integration.adoc diff --git a/docs/guides/modules/ROOT/nav.adoc b/docs/guides/modules/ROOT/nav.adoc index a859227ba0..f23db61d53 100644 --- a/docs/guides/modules/ROOT/nav.adoc +++ b/docs/guides/modules/ROOT/nav.adoc @@ -273,8 +273,6 @@ ** VCS integration *** xref:integration:version-control-system-integration-overview.adoc[VCS integration overview] *** xref:guides:integration:using-the-circleci-github-app-in-an-oauth-org.adoc[Using the CircleCI GitHub App in an OAuth org] -*** xref:integration:gitlab-integration.adoc[GitLab integration] -*** xref:integration:bitbucket-data-center-integration.adoc[Bitbucket data center integration] *** xref:integration:oss.adoc[Build open source projects] ** Third-party integrations diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 8c20286d17..745e5efc52 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -2,7 +2,7 @@ :page-platform: Cloud :page-description: A guide to understanding user accounts, organizations and integrations with version control systems in CircleCI. :experimental: -:page-aliases: guides:integration:github-apps-integration.adoc, guides:integration:github-integration.adoc, guides:integration:bitbucket-integration.adoc, guides:integration:gitlab-integration.adoc +:page-aliases: guides:integration:github-apps-integration.adoc, guides:integration:github-integration.adoc, guides:integration:bitbucket-integration.adoc, guides:integration:gitlab-integration.adoc, guides:integration:bitbucket-data-center-integration.adoc 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. @@ -17,6 +17,8 @@ You can log in to CircleCI using one of the following methods: * Email and password * Social login (GitHub, Bitbucket) +To view your user account integrations, navigate to menu:User Settings[Account Integrations]. + Select your icon in the top bar and select **User settings** to access the following: [#user-settings] @@ -379,9 +381,11 @@ You can view and manage integrations in two places depending on your organizatio === Manage a GitHub App integration -A GitHub App integration is available for `circleci` and `github` organizations. The CircleCI GitHub App is installed in an organization. To see your integration navigate to menu:Organization Settings[Account Integrations]. 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. +A GitHub App integration is available for `circleci` and `github` type organizations. The CircleCI GitHub App is installed into an organization. + +To *view* a GitHub App integration, navigate to menu:Organization Settings[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. -If you would like to uninstall the GitHub App, select the trash/bin button and follow the instructions. +To *uninstall* the GitHub App from your organization, select the trash/bin button and follow the instructions. === Manage a GitHub OAuth app integration @@ -653,13 +657,13 @@ GitLab:: Bitbucket Data Center:: + -- -#TBC# +When you connect a repository with your CircleCI project, behind the scenes, CircleCI is registering a webhook within your Bitbucket Data Center project. You may verify this once you have successfully created the project by navigating to your repository's menu:Project Settings[Webhooks] page. -- ==== === Custom checkout commands -CircleCI provides a `checkout` step that is used to check out your source code. You find find more information about the special `checkout` step in the xref:reference:ROOT:configuration-reference.adoc#checkout[Configuration Reference] page. +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 xref:reference:ROOT:configuration-reference.adoc#checkout[Configuration Reference] page. If you would rather use a custom checkout command you should follow the steps below to ensure the authenticity of the host you are connecting to. From acb7956d5c8a433312aa2e8831d70f13d35ba293 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Tue, 18 Nov 2025 13:05:14 +0000 Subject: [PATCH 20/23] fix link --- docs/guides/modules/orchestrate/pages/pipelines.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/modules/orchestrate/pages/pipelines.adoc b/docs/guides/modules/orchestrate/pages/pipelines.adoc index dbc3203c89..47d944da89 100644 --- a/docs/guides/modules/orchestrate/pages/pipelines.adoc +++ b/docs/guides/modules/orchestrate/pages/pipelines.adoc @@ -102,7 +102,7 @@ To add or edit a pipeline, follow these steps: + NOTE: If you integrate with xref:integration:github-integration.adoc[CircleCI's GitHub OAuth App] you can select GitHub App here to install the App into your org and access xref:integration:using-the-circleci-github-app-in-an-oauth-org.adoc[improved security and new features]. This is a one-time step, which can be done by an organization admin or a user who has admin access to at least one repository in the organization. Once installed, further GitHub App pipelines can be setup without this installation step. + -NOTE: For GitLab self-managed, you can input any instance that you have previously set up in CircleCI. If you wish to set a different feature branch or repository from a self-managed instance as a new pipeline, you will first need to add a new connection via your xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#gitlab-self-managed-integration-setup[menu:Organization Settings[Integrations]]. In either case, you will also need to enter your personal access token again to authorize this connection. +NOTE: For GitLab self-managed, you can input any instance that you have previously set up in CircleCI. If you wish to set a different feature branch or repository from a self-managed instance as a new pipeline, you will first need to add a new connection via your xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#integration-options[menu:Organization Settings[Integrations]]. In either case, you will also need to enter your personal access token again to authorize this connection. ** Authorize your connection if this is not already showing with a check mark image:guides:ROOT:icons/passed.svg[passed icon, role="no-border"]. ** Define where the config file for this pipeline is stored: *** Select a repository from the dropdown. From 7aa6e340703cb47ea9d11447471a1d3b7924526c Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Wed, 26 Nov 2025 13:53:32 +0000 Subject: [PATCH 21/23] some fixes from review --- ...-organizations-and-integrations-guide.adoc | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 745e5efc52..3083f94e0e 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -12,10 +12,10 @@ When you log in to CircleCI you are logging in to your _user account_. As a CircleCI _user_ you can create and access _organizations_. You can access zero, one, or many organizations. You can create new organizations and/or join an existing organization. -You can log in to CircleCI using one of the following methods: +You can log in to CircleCI using one of the following methods. These methods can not be used together, for example, if you have an email/password account and then use a social login, this will create a new account connected to your VCS provider: -* Email and password -* Social login (GitHub, Bitbucket) +* Email and password. +* Social login (GitHub, Bitbucket). To view your user account integrations, navigate to menu:User Settings[Account Integrations]. @@ -30,7 +30,9 @@ Select your icon in the top bar and select **User settings** to access the follo | User settings section | What you will find here | Account Integrations -| Displays your user ID as well as account integrations with VCS providers. You will find a list of which GitHub or Bitbucket organizations you are connected with. You can disconnect your OAuth connections with GitHub or Bitbucket here. +| Displays your user ID as well as account integrations with VCS providers. You will find a list of which GitHub (OAuth app) or Bitbucket organizations you are connected with. You can disconnect your OAuth connections with GitHub or Bitbucket here. + + | Notifications | Set your individual email and web notification preferences. This includes preferences around builds, branches, and project notifications. Web notifications will appear in your browser. @@ -51,11 +53,18 @@ Select your icon in the top bar and select **User settings** to access the follo | See the list of organizations you are a part of. If you have administrative privileges, you may also view the plan each organization is on. | Job SSH keys -| Set up an SSH key to access your job containers. For more information on this feature see the xref:execution-managed:ssh-access-jobs.adoc[Debug with SSH] page. +| Set up an SSH key to access your job containers. For more information on this feature see the xref:execution-managed:ssh-access-jobs.adoc[Debug With SSH] page. | Beta Program | Opt in to CircleCI's beta program. Beta features you opt in to will be listed on this page. +| Email +| View and change your email address for your CircleCI account. + + +| Password & authentication +| Change password, setup and manage multi-factor authentication (MFA). + |=== -- From 6886effe162988988601df87d14a9d1df18df651 Mon Sep 17 00:00:00 2001 From: Rosie Yohannan Date: Wed, 26 Nov 2025 14:05:02 +0000 Subject: [PATCH 22/23] Update docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc Co-authored-by: BeFunes --- .../pages/users-organizations-and-integrations-guide.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index 3083f94e0e..b93b1d4d69 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -83,7 +83,7 @@ Each organization has its own settings, including security, integrations, and re A CircleCI _organization_ can be one of three types: -* `circleci`: This organization type is created separately to any VCS connection between CircleCI and your code repositories. Within a `circleci` organization you create projects and then connect them to your code repositories. +* `circleci`: This organization type exists independently of any VCS connection. Projects within a circleci organization are created in CircleCI first, then connected to your code repositories. * `github`: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. * `bitbucket`: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account. Your Bitbucket repositories appear as projects that can be set up in CircleCI. From bce9df6f69eee76ea3e361cad1a30ffc605db5ee Mon Sep 17 00:00:00 2001 From: Rosie Yohannan Date: Wed, 26 Nov 2025 14:05:45 +0000 Subject: [PATCH 23/23] Update docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc Co-authored-by: BeFunes --- .../pages/users-organizations-and-integrations-guide.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc index b93b1d4d69..06f83d3831 100644 --- a/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -84,7 +84,7 @@ Each organization has its own settings, including security, integrations, and re A CircleCI _organization_ can be one of three types: * `circleci`: This organization type exists independently of any VCS connection. Projects within a circleci organization are created in CircleCI first, then connected to your code repositories. -* `github`: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. +* `github`: This organization type is created automatically when you authorize CircleCI to access your GitHub account via OAuth app (this happens automatically when you sign in with GitHub social login). Your GitHub repositories are imported as available projects in CircleCI. You cannot create projects that don't correspond to existing repositories in your GitHub personal account or organizations. * `bitbucket`: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account. Your Bitbucket repositories appear as projects that can be set up in CircleCI. For full details on creating organizations, see the xref:getting-started:create-an-organization.adoc[Create an organization] page.