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 100% rename from docs/guides/modules/integration/pages/github-apps-integration.adoc rename to archive/github-apps-integration.adoc 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 3036399193..ed46cabefc 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] @@ -270,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 new file mode 100644 index 0000000000..816f095e93 --- /dev/null +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -0,0 +1,793 @@ += 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: +: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 accounts + +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. + +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: + +.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 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 inherited and managed through the VCS provider). + +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: + +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# + +#Org settings table here with tabs for different org types# + +== 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. +-- +==== + +#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: + +* 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. + +=== 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. + +#TODO 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]. + +#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 + +For a guide to inviting you team see the xref:getting-started:invite-your-team.adoc[Invite your team] page. + +== 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. + +=== OAuth permissions + +[tabs] +==== +GitHub OAuth:: ++ +-- +CircleCI requests the following permissions from GitHub, defined in the link:https://developer.github.com/v3/oauth/#scopes[GitHub permissions model]. + +**Read Permission** + +- Get a user's email address + +**Write Permissions** + +- Get a list of a user's repositories +- Add an SSH key to a user's account + +**Admin Permissions**, needed for setting up a project + +- Add deploy keys to a repository +- Add service hooks to a repository + +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]. + + +== 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. + +== 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 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. + +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="9*"] +|=== +|Pipeline type +^|GitHub OAuth trigger +^|Bitbucket Cloud OAuth trigger +^|GitLab trigger +^|Schedule trigger +^|GitHub App trigger +^|Bitbucket Data Center 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-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 +^|[.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 + +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: + +. 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. +**** + +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>>. +-- +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. + +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. +**** + +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 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:: ++ +-- +#TBC# +-- +Bitbucket Data Center:: ++ +-- +#TBC# +-- +==== + +=== 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 + +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. + +Some example tasks where you might need a GitHub 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: +** Pulling private dependencies from other repos your organization owns. +** Checking out submodules from private repositories. +** Running scripts that interact with multiple repos. + +As described above, CircleCI automatically provides a deploy key for the repository being built, but deploy keys have some limitations: + +* Read-only by default. +* Limited to a single repository. +* Can not be reused across multiple repositories. + +A user key bypasses these limitations. + +The trade-off with 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. + +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 + +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). +``` + + +[#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. + +== 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. + +== 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 + +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 + +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. + +== 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. + +==== 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]. + +=== 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[]