diff --git a/docs/guides/modules/integration/pages/bitbucket-data-center-integration.adoc b/archive/bitbucket-data-center-integration.adoc similarity index 100% rename from docs/guides/modules/integration/pages/bitbucket-data-center-integration.adoc rename to archive/bitbucket-data-center-integration.adoc diff --git a/docs/guides/modules/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/integration/pages/gitlab-integration.adoc b/archive/gitlab-integration.adoc similarity index 100% rename from docs/guides/modules/integration/pages/gitlab-integration.adoc rename to archive/gitlab-integration.adoc diff --git a/docs/guides/modules/ROOT/images/gl-ga/gitlab-ga-account-integrations.png b/archive/images/gitlab-ga-account-integrations.png similarity index 100% rename from docs/guides/modules/ROOT/images/gl-ga/gitlab-ga-account-integrations.png rename to archive/images/gitlab-ga-account-integrations.png diff --git a/docs/guides/modules/ROOT/images/gl-ga/gitlab-ga-successful-pipeline.png b/archive/images/gitlab-ga-successful-pipeline.png similarity index 100% rename from docs/guides/modules/ROOT/images/gl-ga/gitlab-ga-successful-pipeline.png rename to archive/images/gitlab-ga-successful-pipeline.png diff --git a/docs/guides/modules/ROOT/images/gl-sm-create-project.png b/archive/images/gl-sm-create-project.png similarity index 100% rename from docs/guides/modules/ROOT/images/gl-sm-create-project.png rename to archive/images/gl-sm-create-project.png diff --git a/docs/guides/modules/ROOT/images/gl-sm-integrations.png b/archive/images/gl-sm-integrations.png similarity index 100% rename from docs/guides/modules/ROOT/images/gl-sm-integrations.png rename to archive/images/gl-sm-integrations.png diff --git a/docs/guides/modules/ROOT/images/triggers/run-on-open.png b/archive/images/run-on-open.png similarity index 100% rename from docs/guides/modules/ROOT/images/triggers/run-on-open.png rename to archive/images/run-on-open.png diff --git a/docs/guides/modules/ROOT/nav.adoc b/docs/guides/modules/ROOT/nav.adoc index cedbb6f6dc..0122b2e01a 100644 --- a/docs/guides/modules/ROOT/nav.adoc +++ b/docs/guides/modules/ROOT/nav.adoc @@ -18,6 +18,7 @@ *** xref:getting-started:language-javascript.adoc[Node.js quickstart] *** xref:getting-started:language-python.adoc[Python quickstart] *** xref:getting-started:language-go.adoc[Go quickstart] +*** xref:getting-started:create-an-organization.adoc[Create an organization] ** Tutorials *** xref:getting-started:config-intro.adoc[Configuration intro] *** xref:getting-started:slack-orb-tutorial.adoc[Use the Slack orb to set up notifications] @@ -219,6 +220,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] @@ -272,12 +274,7 @@ *** 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/cancel-subscription-faq-snip.adoc b/docs/guides/modules/ROOT/partials/faq/cancel-subscription-faq-snip.adoc index 0f6f608afa..7612d26561 100644 --- a/docs/guides/modules/ROOT/partials/faq/cancel-subscription-faq-snip.adoc +++ b/docs/guides/modules/ROOT/partials/faq/cancel-subscription-faq-snip.adoc @@ -16,7 +16,7 @@ For GitHub users, your account has the "Owner" role in your GitHub organization. For Bitbucket Cloud users, your account has "Admin" permissions in your Bitbucket repository. -For GitLab users, your account is listed as "Org Admin" in the CircleCI web app under xref:guides:integration:gitlab-integration.adoc#organization-settings-people[**Organization Settings > People**]. +For GitLab users, your account is listed as "Org Admin" in the CircleCI web app under menu:Organization Settings[People]. [#what-happens-upon-cancelling-a-performance-plan-subscription] === What happens upon cancelling a Performance Plan subscription? diff --git a/docs/guides/modules/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 4f3d6b6f79..a434cdb0aa 100644 --- a/docs/guides/modules/about-circleci/pages/concepts.adoc +++ b/docs/guides/modules/about-circleci/pages/concepts.adoc @@ -466,9 +466,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: @@ -552,12 +552,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#organizations[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..ff76aafda3 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 @@ -38,19 +40,54 @@ Select an **org card** and take a look around. The following section describe th User settings can be found by selecting your user icon at the top right of the user area (dark blue top bar) in the web app at any time. Select your icon and then select ** User Settings**. +.Opening your user settings image::guides:ROOT:user_settings.png[User settings] -**Account Integrations**: Displays your user ID as well as account integrations such as your VCS provider. +[.table-scroll] +-- +.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 (OAuth app) or Bitbucket organizations you are connected with. You can disconnect your OAuth connections with GitHub or Bitbucket here. + + + +| Notifications +| Set your individual email and web notification preferences. This includes preferences around builds, branches, and project notifications. Web notifications will appear in your browser. + +| 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. -**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. +| Personal API tokens +| View and create personal API tokens, used to access the CircleCI API. -**Privacy & Security**: Disable third-party tracking. You may opt in or opt out of third party tracking pixels. +| 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. -**Personal API tokens**: View and create personal API tokens, used to access the CircleCI API. +| 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. -**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. +| Beta Program +| Opt in to CircleCI's beta program. Beta features you opt in to will be listed on this page. -**Beta Program**: Opt in to CircleCI's beta program. Beta features you opt in to will be listed on this page. +| Email +| View and change your email address for your CircleCI account. + + +| Password & authentication +| Change password, setup and manage multi-factor authentication (MFA). + +|=== +-- == Organization homepage and navigation @@ -145,48 +182,66 @@ Access project settings in one of the following ways: image::guides:ROOT:find-project-settings.png[Where to find project settings page in the CircleCI web app] -The following settings are available in the project settings page. If you do not see an option, this indicates it is not supported for your xref:integration:version-control-system-integration-overview.adoc[integration type]: - -**Overview**: Displays your project ID, as well as links to docs on how to set up certain features available to projects. You may also find the option to **Stop Building** on the overview page. This option halts builds, and will automatically _unfollow_ from all dashboards. +The following settings are available on the project settings page. If you do not see an option, this indicates it is not supported for your xref:integration:version-control-system-integration-overview.adoc[organization, integration or pipeline type]: -**People**: Provides a list of users who have been granted project-specific permissions. For more information, see the xref:permissions-authentication:manage-roles-and-permissions.adoc[Manage roles and permissions] page. +The following project settings are available: -**Groups**: Provides a list of user groups that have been granted project-specific permissions. For more information, see the xref:permissions-authentication:manage-groups.adoc[Manage groups] page. +[.table-scroll] +-- +.Project settings +[cols="1,2", options="header"] +|=== +| Project settings section | What you will find here -**Project Setup**: Provides a list of pipelines that have been set up for the project and their associated triggers. See xref:orchestrate:pipelines.adoc[Pipelines Overview and Setup] for more information. This page includes the option to begin setting up pipelines if none exist. The setup UI for schedule triggers is located either here or in the *Triggers* section (if available for your integration). To set up a xref:orchestrate:schedule-triggers.adoc[schedule trigger] you will define a timetable, parameter, and attribution to automatically run a pipeline when the criteria is met. +| Overview +| Project name, ID, and slug. Option to stop building or delete the project. -*Pipelines* and *Triggers*: These pages let you set up pipelines and triggers when using the GitLab, Bitbucket Cloud and Bitbucket Data Center integrations. +| Project setup +| `circleci` and `github` organizations only. Add and manage pipelines and their triggers. Projects for other organization types will have separate Pipelines and Triggers pages. -**Deploys**: A UI for managing and viewing deployments. Setup and manage environment integrations, setup components. For full information on the deploys feature, start with the xref:deploy:deployment-overview.adoc[Deployment overview] page. +| People +| `circleci` organizations only. Assign project-level roles to your team. -**Advanced**: Toggle options on and off for: +| Deploys +| Set up deploy markers, rollback pipeline and find information about setting up the release agent for Kubernetes deployments. -* VCS status updates -* Build forked pull requests -* Pass secrets to builds from forked pull requests +| Advanced +a| Enable/disable various features for the project: +* GitHub status updates +* Build forked PRs +* Pass secrets to forked PRs * Only build pull requests * Auto-cancel redundant workflows * Free and open source -* Enable dynamic config using setup workflows. -* xref:orchestrate:triggers-overview.adoc#trigger-a-pipeline-from-vs-code-with-unversioned-config[Trigger a pipeline with unversioned config]. +* Enable dynamic configuration +* Disable SSH reruns. -More information on these settings can be found on this page, as well as in our documentation. +| Environment variables +| Add project environment variables. You can add individually or import from another project. You will find a list of project environment variables on this page. -**Environment Variables**: Add or import environment variables to your jobs to keep sensitive data out of your repository. +| SSH keys +| Add deploy and user keys for `github` and `bitbucket` organizations. Add additional SSH keys for your project for all organization types. -**SSH Keys**: See information related to your SSH keys, or set up new or additional SSH keys. CircleCI uses deploy and user keys. +| API permissions +| Create project API tokens. The main use for these tokens is for status badges. Some API v1.1 endpoints support the use of project API tokens too. -**API Permissions**: Allows you to create API tokens, as well as revoke project-specific API tokens. +| LLMOps +| Connect your project with an LLM evaluations provider. -**LLMOps**: Set up integrations with LLMOps providers to streamline the process of configuring pipelines to build and test LLM-enabled applications. +| Slack integration +| Get information on setting up Slack notifications for your project. -**Slack Integrations**: Authenticate Slack and set up the Slack orb in your config file to integrate Slack into your projects. +| Status badges +| Generate a code snippet that will display your project's build status in a README or other document. -**Status Badges**: A tool that allows you to generate a code snippet that will display your project's build status in a README or other document. +| Webhooks +| Set up webhooks through CircleCI's Webhook API. This allows you to connect a platform you manage (either an API you create yourself, or a third party service) to a stream of future events. -**Webhooks**: Set up webhooks through CircleCI's Webhook API. This allows you to connect a platform you manage (either an API you create yourself, or a third party service) to a stream of future events. +| Docker layer caching +| Provides an option to delete your cache contents. If jobs that use DLC continuously fail, this may be due to a corrupted cache. Deleting the cache will force a fresh build and can solve the problem. -**Docker layer caching**: Provides an option to delete your cache contents. If jobs that use DLC continuously fail, this may be due to a corrupted cache. Deleting the cache will force a fresh build and can solve the problem. +|=== +-- [#insights] == Insights @@ -216,29 +271,56 @@ Learn more and get started with self-hosted runners on the xref:execution-runner [#organization-settings] == Organization settings -**Overview**: Displays your organization ID and name. Manage technical and security contacts for your org. +The following organization settings are available by selection "Organization Settings" in the sidebar: + +[.table-scroll] +-- +.Organization settings +[cols="1,2", options="header"] +|=== +| Organization settings section | What you will find here + +| Overview +| Org ID and slug, option to rename or delete the organization. Manage technical and security contacts. + +| People +| For `circleci` organizations find a list of organization members and their roles. For all organizations you will find the option to invite new members to the organization. + +|Groups +| `circleci` organizations only. Create and manage groups of org members. You can assign roles to groups to manage permissions. -**People**: Manage user roles and permissions within your organization, or generate org invites. +| Contexts +| Create and manage contexts to store sensitive information. You can use contexts to store environment variables for your projects. -**Groups**: Manage group level permissions for users in your organization. +| VCS Connections +| View Apps you have installed for your organization: GitHub App and GitHub Checks App. -**Contexts**: Set up a new context, view a list of existing contexts, or remove contexts. Contexts provide a mechanism for securing and sharing environment variables across projects. +| Security +| Orb security settings, you can choose to allow just certified orbs, all orbs, and choose to allow private orbs. Request audit logs and/or set up audit log streaming. -**VCS**: Menu will differ per VCS. For example, if your VCS is GitHub, you can manage GitHub Checks. +| Policies +| Find a list of policies that have been created for your organization. -**Security**: Allows you to set whether or not you want to allow the use of partner and community orbs, or private orbs. Depending on your plan, you can also set up a security contact to retrieve audit logs. +| Advanced +| Opt in/out of the following: intelligent summaries for build failures, image brownouts, triggering pipelines with unversioned config. -**Policies**: Provides a list of all policies that have been set up for your organization. For more information on config policies, see the xref:config-policies:config-policy-management-overview.adoc[Config policy management overview]. +| Orbs +| For `circleci` organizations you will find your URL orb allow list. FOr `github` and `bitbucket` organizations you will find registry information for orbs that have been authored by your organization. -**Advanced**: Enable/disable the use of xref:toolkit:intelligent-summaries.adoc[intelligent summaries] for contextual help with build failures. Some orgs have the option to allow xref:orchestrate:triggers-overview.adoc#trigger-a-pipeline-from-vs-code-with-unversioned-config[triggering pipelines with unversioned config] from VS Code. +| Self-hosted runners +| Set up self-hosted runners for your organization, to build on your own infrastructure. -**Orbs**: View a list of all the orbs authored by your organization. +| Deploys +| Find information on setting up deploys and/or the release agent. -**Self-Hosted Runners**: Accept the terms of use to enable self-hosted runners. Once accepted, you can visit the self-hosted runner section of the web application to create resource classes and set up runners. +| Integrations +| `circleci` organizations only. Integration set up for GitLab self-managed and Bitbucket Data Center. -**Deploys**: Find links to set up deploy markers or deploy monitoring for your projects. +| Singe sign-on +| `circleci` organizations on Scale Plan only. Set up SSO for your organization. -**Integrations**: Set up integrations with self-hosted version control systems. +|=== +-- [#plan] == Plan diff --git a/docs/guides/modules/deploy/pages/deploy-to-azure-container-registry.adoc b/docs/guides/modules/deploy/pages/deploy-to-azure-container-registry.adoc index 257beab42a..c4e8e312d5 100644 --- a/docs/guides/modules/deploy/pages/deploy-to-azure-container-registry.adoc +++ b/docs/guides/modules/deploy/pages/deploy-to-azure-container-registry.adoc @@ -59,4 +59,4 @@ workflows: only: main # Only deploys when the commit is on the `main` branch ``` -If pushing to your repository is required, see the "Deployment Keys" section of the xref:integration:github-integration.adoc#deploy-keys-and-user-keys[GitHub] or xref:integration:bitbucket-integration.adoc#deploy-keys-and-user-keys[Bitbucket Cloud] instructions. Then, configure the Azure Web App to use your production branch. +If pushing to your repository is required, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#enable-project-to-check-out-additional-private-repositories[Users, Organizations, and Integrations Guide]. Then, configure the Azure Web App to use your production branch. diff --git a/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc b/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc index 21d3ca5396..d9468feb37 100644 --- a/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc +++ b/docs/guides/modules/deploy/pages/set-up-rollbacks.adoc @@ -59,7 +59,7 @@ image::guides:ROOT:deploy/project-overview-rollback.png[Rollback button on proje === 2. Confirm GitHub App installation -NOTE: To set up rollback pipelines, you must 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[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-an-organization.adoc b/docs/guides/modules/getting-started/pages/create-an-organization.adoc new file mode 100644 index 0000000000..f47f05ada4 --- /dev/null +++ b/docs/guides/modules/getting-started/pages/create-an-organization.adoc @@ -0,0 +1,53 @@ += Create an organization +:page-platform: Cloud +:page-description: Create a new organization in CircleCI. +:experimental: + +This guide covers creating a new organization in CircleCI. + +The following organization types are available in CircleCI: + +* `circleci` +* `github` +* `bitbucket` + +For a guide to organization types, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organizations[Users, Organizations, and Integrations Guide]. + +== Create a circleci organization + +To create a `circleci` organization, follow these steps: + +. Navigate to your user homepage in the link:https://app.circleci.com/home/[CircleCI web app]. +. Select the btn:[+ Create organization] button. +. Give your organization a name and select btn:[Let's Go]. + +Once your new organization is created you can start creating projects and inviting team members: + +* xref:create-project.adoc#create-a-project[Create a Project] +* xref:invite-your-team.adoc#invite-teammates[Join Teammates on CircleCI] + +== Create a github organization + +A `github` organization is created when you log in to CircleCI using your _social_ GitHub login. `github` organizations use an OAuth app connection with CircleCI. If you have logged in to CircleCI using a method other than your GitHub login, you can still create a `github` organization by following these steps: + +. Navigate to your link:https://app.circleci.com/settings/user[User settings] page. +. Select the **Account Integrations** from the sidebar. +. At the bottom of the page, select the link that reads `Recieved instructions from the CircleCI Support team to authorize a GitHub OAuth app?` +. Follow the instructions to create a `github` organization. + +Once your `github` organization is created you can start setting up and following projects: + +* xref:create-project.adoc#set-up-a-project[Set up a project] + +== Create a `bitbucket` organization + +A `bitbucket` organization is created when you log in to CircleCI using your _social_ Bitbucket login. `bitbucket` organizations use an OAuth app connection with CircleCI. If you have logged in to CircleCI using a method other than your Bitbucket login, you can still create a `bitbucket` organization by following these steps: + +. Navigate to your link:https://app.circleci.com/settings/user[User settings] page. +. Select the **Account Integrations** from the sidebar. +. Select btn:[Connect] next to Bitbucket. +. Follow the instructions to authorize the Bitbucket OAuth app. + +Once your `bitbucket` organization is created you can start setting up and following projects: + +* xref:create-project.adoc#set-up-a-project[Set up a project] \ No newline at end of file diff --git a/docs/guides/modules/getting-started/pages/create-project.adoc b/docs/guides/modules/getting-started/pages/create-project.adoc index c78c651dfa..6938c9453c 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: @@ -67,6 +69,9 @@ Once your project is created you will land on your pipelines page. GitLab Cloud:: + -- + +NOTE: **Remove GitLab CI/CD config** You should remove the `.gitlab-ci.yml` file from projects you integrate with CircleCI. This prevents you from having CI/CD builds happening in both systems. There is an option to _disable_ GitLab CI/CD for a project in the GitLab UI but using this is **not recommended**. + Follow these steps to create a new project in CircleCI: include::ROOT:partial$create-project/steps-up-to-pipeline.adoc[Insert steps from selecting Create project up to setting up a pipeline] @@ -105,15 +110,21 @@ image::guides:ROOT:create-project/download-config-file.png[Modal showing options GitLab self-managed:: + -- +CAUTION: Before creating a project that you want to integrate with code in a GitLab self-managed instance, you need to set up an integration with your GitLab self-managed instance. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organization-integration[GitLab self-managed integration setup] page for more information. + +NOTE: **Remove GitLab CI/CD config** You should remove the `.gitlab-ci.yml` file from projects you integrate with CircleCI. This prevents you from having CI/CD builds happening in both systems. There is an option to _disable_ GitLab CI/CD for a project in the GitLab UI but using this is **not recommended**. + Follow these steps to create a new project in CircleCI: include::ROOT:partial$create-project/steps-up-to-pipeline.adoc[Insert steps from selecting Create project up to setting up a pipeline] -. Choose a repo to connect to your project. If you do not see your repo listed, select btn:[Add] or btn:[Connect to GitLab self-managed] to access repositories from your GitLab self-managed instance. Select btn:[GitLab self-managed] and then btn:[Authorize in GitLab self-managed] +. Choose a repo to connect to your project. If you do not see your repo listed, select btn:[Add] to access repositories from your GitLab self-managed instance. + .Choose a repo to connect your code to your project image::guides:ROOT:create-project/choose-a-repo-gitlab.png[Choose a repository window with option to add another VCS] + +Select btn:[GitLab self-managed] and then btn:[Authorize in GitLab self-managed] ++ .Authorize GitLab self-managed image::guides:ROOT:create-project/authorize-gitlab-self-managed.png[Option to authorize a new VCS integration] @@ -123,16 +134,14 @@ image::guides:ROOT:create-project/authorize-gitlab-self-managed.png[Option to au image::guides:ROOT:create-project/create-new-gitlab-self-managed-project.png[Create new project window] + **** -If this is your first GitLab self-managed project you will now set up your integration: - -* Verify your GitLab URL -* Generate an add a personal access token -* Add your known hosts, following the instructions in the app +If you set up your GitLab self-managed instance you should see your instance URL and known_hosts. If not see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organization-integration[integration instructions]. **** +* Generate and add a personal access token with the `api` scope. -** Use the repository dropdown menu to tell CircleCI where your code is stored. -** Select **Create Project**. You will then be redirected to the Pipelines page. -** The express CircleCI configuration setup is not currently available for GitLab self-managed projects. You will need to add a `.circleci/config.yml` file in your repository if it has not yet been set up. If the repository you selected already contains a `.circleci/config.yml`, push a commit to see your pipeline on the dashboard. +** Use the Repository dropdown menu to tell CircleCI where your code is stored. +** Use the Branch dropdown to tell CircleCI which branch to use for your pipeline. +** Select **Save**. You will then be redirected to the Pipelines page. +** The express CircleCI configuration setup is not currently available for GitLab self-managed projects. You will need to add a `.circleci/config.yml` file in your repository. If the repository you selected already contains a `.circleci/config.yml`, push a commit to see your pipeline on the dashboard. + **** For guidance on creating a `config.yml` file, see the following pages: @@ -145,19 +154,27 @@ For guidance on creating a `config.yml` file, see the following pages: Bitbucket Data Center:: + -- +CAUTION: Before creating a project that you want to integrate with code in a Bitbucket Data Center instance, you need to set up an integration with your Bitbucket Data Center instance. See the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organization-integration[Bitbucket Data Center integration setup] page for more information. + Follow these steps to create a new project in CircleCI: include::ROOT:partial$create-project/steps-up-to-pipeline.adoc[Insert steps from selecting Create project up to setting up a pipeline] -. Choose a repo to connect to your project. If you do not see your repo listed, select btn:[Add] to access repositories from GitHub. Select btn:[Bitbucket Data Center] and then btn:[Authorize in Bitbucket Data Center] +. Choose a repo to connect to your project. If you do not see your repo listed, select btn:[Add]. Select btn:[Bitbucket Data Center] and then btn:[Authorize in Bitbucket Data Center] + .Access Bitbucket data center repos image::guides:ROOT:create-project/authorize-bitbucket-data-center.png[Choose a repository window with option to add another VCS] -. Next, follow the steps on the xref:integration:bitbucket-data-center-integration.adoc#integrate-a-project-with-circleci[Bitbucket integration setup] page to set up the following: -** An integration with your Bitbucket Data Center instance (if not already set up for your org). -** Set up a pipeline and trigger for your project. -** Add a configuration file to your repo. +. To set up your project you will need to create a project HTTP access token with the project admin scope. Create this under Projects in Bitbucket. For more information, see the link:https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html[Bitbucket docs]. Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI. ++ +**** +If you set up your Bitbucket Data Center instance you should see your instance URL and known_hosts. If not see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organization-integration[integration instructions]. +**** + +** Use the repository dropdown menu to tell CircleCI where your code is stored. +** Use the Branch dropdown to tell CircleCI which branch to use for your pipeline. +** Select **Save**. You will then be redirected to the Pipelines page. +** The express CircleCI configuration setup is not currently available for Bitbucket Data Center projects. You will need to add a `.circleci/config.yml` file in your repository. If the repository you selected already contains a `.circleci/config.yml`, push a commit to see your pipeline on the dashboard. -- ==== diff --git a/docs/guides/modules/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..3b9c422115 100644 --- a/docs/guides/modules/integration/pages/add-ssh-key.adoc +++ b/docs/guides/modules/integration/pages/add-ssh-key.adoc @@ -3,9 +3,9 @@ :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. +TIP: If you want to set up an SSH key in order to checkout code from additional repositories in GitHub or Bitbucket Cloud and and you have a `github` or `bitbucket` organization, see the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#create-a-user-key[Users, Organizations, and Integrations Guide] for steps to add a user key. Alternatively follow steps on this page to add additional SSH keys to your project. You may need to add the public key to `~/.ssh/authorized_keys` in order to add SSH keys. @@ -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/integration/pages/oss.adoc b/docs/guides/modules/integration/pages/oss.adoc index 3762254812..3a0c6d4bdb 100644 --- a/docs/guides/modules/integration/pages/oss.adoc +++ b/docs/guides/modules/integration/pages/oss.adoc @@ -111,7 +111,7 @@ Running an unrestricted build in a parent repository can be dangerous. Projects By default, CircleCI does not pass secrets to builds from forked PRs for open source projects and hides four types of configuration data: * <> set through the application. -* xref:github-integration.adoc#deploy-keys-and-user-keys[Deployment keys and user keys]. +* xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#create-a-user-key[Deployment keys and user keys]. * Passphraseless private SSH keys you have xref:add-ssh-key.adoc[added to CircleCI] to access arbitrary hosts during a build. * xref:deploy:deploy-to-aws.adoc[AWS permissions] and configuration files. diff --git a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc index 31b2c09860..5f9efddc18 100644 --- a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc +++ b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc @@ -97,7 +97,7 @@ include::ROOT:partial$tips/check-github-type.adoc[Check your GitHub integration ^1^ _Possible using xref:orchestrate:dynamic-config.adoc[dynamic configuration]._ -^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:github-integration.adoc#using-github-app-functionality[here]._ +^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:using-the-circleci-github-app-in-an-oauth-org.adoc[here]._ ^3^ _When GitHub Checks are enabled we automatically disable GitHub status updates to avoid duplication of statuses. You can manage GitHub status updates via project settings._ @@ -170,7 +170,7 @@ include::ROOT:partial$tips/check-github-type.adoc[Check your GitHub integration ^1^ _One alternative is to use a xref:orchestrate:custom-webhooks.adoc[custom webhook] to generate a URL that you `curl` with a 3rd party scheduling tool._ -^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:github-integration.adoc#using-github-app-functionality[here]._ +^2^ _Enable by using the GitHub App integration alongside the OAuth app integration. More details xref:using-the-circleci-github-app-in-an-oauth-org.adoc[here]._ ^3^ _For GitLab Cloud and GitLab self-managed projects, you can choose to trigger pipelines upon the creation of merge requests, by selecting the *Only Build Merge Requests* trigger filter._ diff --git a/docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc b/docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc index 5136001ae9..ff22e66b25 100644 --- a/docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc +++ b/docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc @@ -169,7 +169,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/pipelines.adoc b/docs/guides/modules/orchestrate/pages/pipelines.adoc index 36ff96a34f..ce96ee0df0 100644 --- a/docs/guides/modules/orchestrate/pages/pipelines.adoc +++ b/docs/guides/modules/orchestrate/pages/pipelines.adoc @@ -100,9 +100,9 @@ To add or edit a pipeline, follow these steps: ** Give your pipeline a descriptive name, for example `Run tests and deploy`. ** Under Integration select the platform that matches where your project is set up (for example, GitHub App). + -NOTE: If you integrate with xref:integration:github-integration.adoc[CircleCI's GitHub OAuth App] you can select GitHub App here to install the App into your org and access xref:integration:github-integration.adoc#using-github-app-functionality[improved security and new features]. This is a one-time step, which can be done by an organization admin or a user who has admin access to at least one repository in the organization. Once installed, further GitHub App pipelines can be setup without this installation step. +NOTE: If you integrate with xref:integration:github-integration.adoc[CircleCI's GitHub OAuth App] you can select GitHub App here to install the App into your org and access xref:integration:using-the-circleci-github-app-in-an-oauth-org.adoc[improved security and new features]. This is a one-time step, which can be done by an organization admin or a user who has admin access to at least one repository in the organization. Once installed, further GitHub App pipelines can be setup without this installation step. + -NOTE: For GitLab self-managed, you can input any instance that you have previously set up in CircleCI. If you wish to set a different feature branch or repository from a self-managed instance as a new pipeline, you will first need to add a new connection via your xref:integration:gitlab-integration.adoc#organization-settings-integrations[menu:Organization Settings[Integrations]]. In either case, you will also need to enter your personal access token again to authorize this connection. +NOTE: For GitLab self-managed, you can input any instance that you have previously set up in CircleCI. If you wish to set a different feature branch or repository from a self-managed instance as a new pipeline, you will first need to add a new connection via your xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#organization-integration[menu:Organization Settings[Integrations]]. In either case, you will also need to enter your personal access token again to authorize this connection. ** Authorize your connection if this is not already showing with a check mark image:guides:ROOT:icons/passed.svg[passed icon, role="no-border"]. ** Define where the config file for this pipeline is stored: *** Select a repository from the dropdown. @@ -112,6 +112,23 @@ NOTE: For GitLab self-managed, you can input any instance that you have previous Once you have set up a pipeline you need to set up a trigger to connect it to. Setting up a trigger is described in the following section. -- +Bitbucket Data Center:: ++ +-- +To add or edit a pipeline, follow these steps: + +. In the CircleCI web app, select **Projects** in the sidebar. +. Select the ellipsis next to your project image:guides:ROOT:icons/more.svg[more icon, role="no-border"] and choose **Project Settings**. +. Select **Pipelines** in the sidebar. +. Select btn:[Add Pipeline], or, if you wish to edit an existing pipeline select the pencil icon on the right. +. Complete the form fields and options: +** Give your pipeline a descriptive name, for example `Run tests and deploy`. +** Under Integration select the platform that matches where your project is set up (for example, Bitbucket Data Center). +** Authorize your connection if this is not already showing with a check mark image:guides:ROOT:icons/passed.svg[passed icon, role="no-border"]. +** Define where the config file for this pipeline is stored: +*** Select a repository from the dropdown. +*** Enter the path to the config file. +-- ==== == Pipeline states diff --git a/docs/guides/modules/orchestrate/pages/set-up-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/orchestrate/pages/set-up-triggers.adoc b/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc index 802bf13d62..61b1748f70 100644 --- a/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc +++ b/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc @@ -100,7 +100,29 @@ To verify your trigger is set up correctly, trigger an event from your repositor Bitbucket Data Center:: + -- -For steps to add a trigger for a pipeline using Bitbucket Data Center, see the xref:integration:bitbucket-data-center-integration.adoc[Bitbucket Data Center] page. +To add a trigger for a pipeline, follow these steps: +. In the CircleCI web app, select **Projects** in the sidebar. +. Select the ellipsis next to your project image:guides:ROOT:icons/more.svg[more icon, role="no-border"] and choose **Project Settings**. +. Select **Triggers** in the sidebar. +. Select btn:[Add Trigger]. +. Select the same location in the "Connect to" dropdown menu that you selected for your pipeline (for example, Bitbucket Data Center). +. Select btn:[Next]. +. Complete the form fields and options: +** Give your trigger a descriptive name. +** Authorize your connection if this is not already showing with a check mark image:guides:ROOT:icons/passed.svg[passed icon, role="no-border"] (Not required for custom webhooks). +** Provide the project HTTP access token you created above. Select btn:[Connect]. +** Select the Trigger source repository +. If you have not already done so, **create a `.circleci` directory to the root of your repository, then add a `config.yml` file in that directory**. When you commit this change in your repository, you should see the pipeline trigger for the first time on the CircleCI dashboard. ++ +**** +For help with creating a CircleCI `config.yml`, see the following pages: + +* xref:getting-started:hello-world.adoc[Hello world] +* xref:toolkit:sample-config.adoc[Sample config] +* xref:reference:ROOT:configuration-reference.adoc[Configuration reference] +**** + +Each time you push changes to your Bitbucket Data Center repository, a new pipeline is triggered and you should see it running for the project within the CircleCI web app. -- Scheduled:: + diff --git a/docs/guides/modules/orchestrate/pages/triggers-overview.adoc b/docs/guides/modules/orchestrate/pages/triggers-overview.adoc index 6bb4556d93..28dc37e7a5 100644 --- a/docs/guides/modules/orchestrate/pages/triggers-overview.adoc +++ b/docs/guides/modules/orchestrate/pages/triggers-overview.adoc @@ -167,6 +167,12 @@ NOTE: Schedule triggers are not available for GitLab and Bitbucket Data Center p Schedule triggers allow you to trigger pipelines periodically based on a schedule. To get this set up for a project you can either use the CircleCI web app or use the link:https://circleci.com/docs/api/v2/index.html#operation/createSchedule[API v2]. For full details of both methods see the xref:schedule-triggers.adoc[Schedule Triggers] docs. +== GitHub webhook settings + +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. + [#next-steps] == Next steps 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 edf2c469e0..ceef64252f 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..f63cdf197b --- /dev/null +++ b/docs/guides/modules/permissions-authentication/pages/users-organizations-and-integrations-guide.adoc @@ -0,0 +1,1023 @@ += 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, guides:integration:gitlab-integration.adoc, guides:integration:bitbucket-data-center-integration.adoc + +This guide explains the concepts of user, organization, and integration in CircleCI. After these concepts are covered, you can find out about the features available to you depending on your organization and pipeline type. + +== User accounts + +When you log in to CircleCI you are logging in to your _user account_. + +You can log in to CircleCI using one of the following methods. These methods can not be used together. For example, if you have an email/password account and then use a social login, this will create a new account connected to your VCS provider: + +* Email and password. +* Social login (GitHub, Bitbucket). + +As a CircleCI _user_ you can create and access _organizations_. You can access zero, one, or many organizations. You can create new organizations and/or join an existing organization. + +A CircleCI user account can be integrated with VCS user accounts via _authorization_. + +The following table describes user authorization for the different VCS providers: + +[.table-scroll] +-- +.User account integration authorization types +[cols=4*, options="header"] +|=== +| VCS provider | Authorization type | Authorization management | Notes + +|GitHub +|GitHub OAuth app +|Displayed in menu:User Settings[Account Integration], managed in GitHub at link:https://github.com/settings/applications[GitHub settings]. +|Can exist alongside GitHub App authorization. + +|GitHub +|GitHub App +|If you are not "authorized" you will see a button in the top bar of the web app that prompts you to authorize. Managed in GitHub at link:https://github.com/settings/apps/authorizations[GitHub settings]. Not displayed in menu:User Settings[Account Integration]. +|Can exist alongside GitHub OAuth app authorization. + +|Bitbucket +|Bitbucket Cloud OAuth +|Displayed in menu:User Settings[Account Integrations] , managed in Bitbucket at link:https://bitbucket.org/account/settings/app-authorizations/[Bitbucket settings]. +|Mutually exclusive with other VCS authorization + +|GitLab +|TBC +|Managed in Gitlab at link:https://gitlab.com/-/user_settings/applications[GitLab settings]. Not displayed in menu:User Settings[Account Integrations]. +|Mutually exclusive with other VCS authorizaitons except GitHub App. +|=== +-- + +== 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). + +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: + +[.table-scroll] +-- +[cols=4*, options="header"] +|=== +| Organization type | VCS integrations available | Projection creation process | Notes + +| `circleci` +a| * GitHub App (add-on) +* GitLab (add-on) +* GitLab self-managed (add-on) +* Bitbucket Data Center (add-on) +| Created manually via web app or API +| This organization type is created separately to any VCS connection between CircleCI and your code repositories. + +| `github` +a| * GitHub App (add-on) +* GitHub OAuth app (built-in) +| Imported from VCS automatically. +| Created automatically when you authorize CircleCI to access your GitHub account via OAuth app. This happens automatically when you sign in to CircleCI with your GitHub social login. + +| `bitbucket` +a| * Bitbucket OAuth (built-in) +| Imported from VCS automatically. +| Created automatically when you authorize CircleCI to access your Bitbucket account via OAuth app. This happens automatically when you sign in to CircleCI with your Bitbucket social login. + +|=== +-- + +include::ROOT:partial$tips/check-org-type.adoc[Check your organization type] + +For full details on creating organizations, see the xref:getting-started:create-an-organization.adoc[Create an Organization] page. + +=== Projects + +[tabs] +==== +`github` organizations:: ++ +-- +For `github` organizations projects are created automatically from your VCS 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. Commit a CircleCI `config.yml` file to the repository to define your pipeline. This creates a GitHub OAuth pipeline for you, which you can view in menu:Project Settings[Project Setup]. +* Follow/unfollow projects, to subscribe/unsubscribe from notifications for builds. + +If you install the CircleCI GitHub App into your organization you can create new GitHub App pipelines and triggers alongside existing OAuth pipelines. GitHub App pipelines and triggers are not bound to the project repository. For example: + +* You could set up a trigger for your pipeline that runs not only when someone pushes to the repository itself, but also when there is a push to the default branch of a library your project depends on. +* You could create a new pipeline within the project that uses a configuration file from a centrally managed repository but is triggered on events in the project repository. + +When you set up a project to build with CircleCI, the following settings are added to the repository using the permissions you gave CircleCI when you signed up: + +- A deploy key that is used to check out your project from GitHub. +- A webhook that is used to notify CircleCI when you push to GitHub. + +CircleCI builds push events by default. Builds are triggered for all pushes to the repository and push is the most common case of triggering a build. +-- +`bitbucket` organizations:: ++ +-- +For `bitbucket` organizations, projects are created automatically from your VCS 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. Commit a CircleCI `config.yml` file to the repository to define your pipeline. This creates a Bitbucket Cloud pipeline for you, which you can view in 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. +-- +`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. +-- +==== + +=== Organization integration + +The organizaiton integration options available to you depend on your organization type. By _integration_ here we mean the way CircleCI checks out your code from your VCS provider. Options are as follows: + +[.table-scroll] +-- +[cols=6*, options="header"] +|=== +| Organization type |GitHub App | GitHub OAuth | Bitbucket Cloud | Bitbucket Data Center | GitLab + +| `circleci` +| [.circle-green]#Yes# +| [.circle-red]#No# +| [.circle-red]#No# +| [.circle-green]#Yes# +| [.circle-green]#Yes# + +|`github` +| [.circle-green]#Yes# +| [.circle-green]#Yes# +| [.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# + +|=== +-- + +Integrations are set up as follows: + +* GitHub OAuth and Bitbucket Cloud are set up when logging in to CircleCI with your GitHub or Bitbucket social login. No additional action is required, but the installation can be viewed at menu:Organization Settings[VCS Connections]. +* GitHub App, GitLab self-managed and Bitbucket Data Center are managed from menu:Organization Settings[VCS Connections]. However, when creating a project (if using a `circleci` organization) or creating a new pipeline from menu:Project Settings[Project setup] you will also be walked through the installation process. +* GitLab SaaS installation is set up when creating a new project (menu:Projects[Create project]) or a new pipeline (menu:Project Settings[Pipelines]) + +If you are using a self-hosted GitLab instance or Bitbucket Data Center instance, some additional configuration is required as follows. See he <> section for more information. + +== Limitations + +The following limits are currently in place for the Free Plan: + +- Each user can create up to three `circleci` organizations on the Free Plan. +- Each `circleci` organization under a Free Plan can have up to 10 projects. + +If you need more organizations or projects, consider upgrading to a Paid Plan or link:https://support.circleci.com/hc/en-us/requests/new[contact our Support team]. See hte xref:plans-pricing:plan-overview.adoc[Plan Overview] page for more information. + +== 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 Try]. +* xref:getting-started:invite-your-team.adoc[Join Teammates on CircleCI]. +* 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]. + +== Manage organization integrations + +The following sections describe your options for each integration type. + +[tabs] +==== +GitHub App:: ++ +-- +*Availability*: A GitHub App integration is available for `circleci` and `github` type organizations. The CircleCI GitHub App is installed into an organization. + +*View*: To view a GitHub App integration, navigate to menu:Organization Settings[VCS Connections]. If you are in a `circleci` or `github` organization you will either see your active GitHub App integration or an option to install the GitHub App. + +*Disconnect*: To *uninstall* the GitHub App from your organization, select the trash/bin button and follow the instructions. +-- +GitHub OAuth:: ++ +-- +*Availability*: A GitHub OAuth app integration is installed into a `github` type organization. + +*View*: To *view* a GitHub OAuth app integration, navigate to menu:Organization Settings[VCS Connections]. If the GitHub OAuth app is installed you will see this indicated in the OAuth app section. + +*Disconnect*: You can _disconnect_ your GitHub OAuth app integration. Doing so will remove your `github` organization from CircleCI. To disconnect your GitHub OAuth app integration, navigate to menu:User Settings[Account Integrations], select btn:[Disconnect] next to your GitHub integration and follow the instructions. +-- +Bitbucket:: ++ +-- +*Availability*: A Bitbucket Cloud integration is installed into a `bitbucket` type organization. + +*View*: To *view* a Bitbucket Cloud integration, navigate to menu:Organization Settings[VCS Connections]. If the Bitbucket Cloud integration is installed you will see this indicated in the Bitbucket Cloud section. + +*Disconnect*: You can _disconnect_ your Bitbucket Cloud integration. Doing so will remove your `bitbucket` type organization from CircleCI. To disconnect your Bitbucket Cloud integration, navigate to menu:User Settings[Account Integrations], select btn:[Disconnect] next to your Bitbucket Cloud integration and follow the instructions. +-- +GitLab:: ++ +-- +*Availability*: A GitLab SaaS integration is installed into a `circleci` type organization. + +*View*: Currently, there is no method to manage the connection with GitLab outside of the project setup, trigger, and configuration settings. + +*Disconnect*: Currently, there is no method to disconnect GitLab from your organization. You can delete projects that are connected to GitLab. and delete the CircleCI webhooks in GitLab to achieve this. See the xref:security:delete-organizations-and-projects.adoc[Delete Organizations and Projects] page for more information. +-- +GitLab self-managed:: ++ +-- + +NOTE: If you are using both CircleCI's Bitbucket Data Center and GitLab self-managed integrations, there is a known bug in the menu:Organization Settings[Integrations] section of the CircleCI web app. Adding a `known_hosts` to one integration will populate the `known_hosts` for the other integration. To use both Bitbucket Data Center and GitLab self-managed integrations within the same CircleCI organization, add both respective `known_hosts` values to the one input field separated by a new line. + +*Availability*: A GitLab self-managed integration is installed into a `circleci` type organization. + +*Configure*: Set up an integration with your GitLab self-managed instance from menu:Organization Settings[Integrations] as follows: + +. Select btn:[Set Up Integration] next to GitLab self-managed. +. Enter your GitLab self-managed instance URL, for example, `https://test-gitlab.circleci.com`. ++ +Your self-managed instance must already contain at least one GitLab project. The authorization attempt will be unsuccessful if your instance does not have any projects. Note that the self-managed instance must be accessible via the public internet. If the self-managed instance is behind a firewall, see link:https://discuss.circleci.com/t/gitlab-self-managed-support-on-circleci-is-now-here/47726/3?u=sebastian-lerner[a suggested workaround]. + +. Enter your instance's SSH public host keys. You can retrieve this from your instance by running `ssh-keyscan `, for example, `ssh-keyscan test-gitlab.circleci.com`, and copying the command's output. ++ +The output should look something like: ++ +[,shell] +---- +➜ ~ ssh-keyscan test-gitlab.circleci.com + +# gitlab.com:22 SSH-2.0-GitLab-SSHD +gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9 +# gitlab.com:22 SSH-2.0-GitLab-SSHD +gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY= +# gitlab.com:22 SSH-2.0-GitLab-SSHD +gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf +# gitlab.com:22 SSH-2.0-GitLab-SSHD +# gitlab.com:22 SSH-2.0-GitLab-SSHD +---- + +. Select btn:[Set Up Integration]. + +To create pipelines for your code in GitLab self-managed, you will need to generate a link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html[personal access token]. This token must have the `api` scope. + +You cannot currently edit or delete existing GitLab self-managed integrations. + +*View*: Currently, there is no method to manage the connection with GitLab self-managed outside of the project setup, trigger, and configuration settings. + +*Disconnect*: Currently, there is no method to disconnect GitLab self-managed from your organization. You can delete projects that are connected to GitLab self-managed and delete the CircleCI webhooks in GitLab to achieve this. See the xref:security:delete-organizations-and-projects.adoc[Delete Organizations and Projects] page for more information. +-- +Bitbucket Data Center:: ++ +-- +NOTE: If you are using both CircleCI's Bitbucket Data Center and GitLab self-managed integrations, there is a known bug in the menu:Organization Settings[Integrations] section of the CircleCI web app. Adding a `known_hosts` to one integration will populate the `known_hosts` for the other integration. To use both Bitbucket Data Center and GitLab self-managed integrations within the same CircleCI organization, add both respective `known_hosts` values to the one input field separated by a new line. + +*Availability*: A Bitbucket Data Center integration is installed into a `circleci` type organization. + +*Configure*: Set up an integration with your Bitbucket Data Center instance from menu:Organization Settings[Integrations] as follows: + +. Select btn:[Set up integration] next to Bitbucket Data Center. +. In the modal enter your Bitbucket Data Center instance URL and your `known_hosts`: ++ +Integrating CircleCI with your Bitbucket Data Center instance requires that you store a public SSH host key within the CircleCI organization that will be accessing the Bitbucket Data Center instance. ++ +To get the required SSH host key, run `ssh-keyscan` with the hostname and port of your Bitbucket Data Center instance. For example: ++ +TIP: Replace the port with the correct port for your instance, and the hostname with your Bitbucket Data Center hostname. ++ +[,shell] +---- +ssh-keyscan -p 1234 bitbucket-datacenter.example.com +---- ++ +The output will look something like the following: ++ +[,shell] +---- +[bitbucket-datacenter.example.com]:1234 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAA//NF6iU86j0hfGxn8ncjgwvmk9tMKzhFqrRLaltP0TGt760PhfWk070raKLHS3L6H0BdN9qNVsTk63czziFDmtBehE82/XXX+59MuppY0DHG3brNvw4REPmzZkQNIR6Cs8b15iFbwnIL51IH9kBVMztWQaRDPkPPxihM6e0n/vo5n3uEIPCTZiwLgKRcpeks2LsfbsW0NN5Q7J1Irp/ACstfrsFWSntranbjMe6cIwELNY6FhvYmETzH0cY0= +---- ++ +Copy the full output from the `ssh-keyscan` command and enter it into the "known hosts" text box when setting up your integration in the CircleCI web app under menu:Organization Settings[Integrations]. + +. Select btn:[Set Up Integration]. + +To set up Bitbucket data center pipelines you will need to create a project HTTP access token with the project admin scope. Create this under Projects in Bitbucket. For more information, see the link:https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html[Bitbucket docs]. Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI. + +*View*: Currently, there is no method to manage the connection with Bitbucket Data Center outside of the project setup, trigger, and configuration settings. + +*Disconnect*: Currently, there is no method to disconnect Bitbucket Data Center from your organization. You can delete projects that are connected to Bitbucket Data Center and delete the CircleCI webhooks in Bitbucket Data Center to achieve this. See the xref:security:delete-organizations-and-projects.adoc[Delete Organizations and Projects] page for more information. +-- +==== + +=== Can multiple CircleCI organizations connect to the same GitHub organization? + +A GitHub organzization can only be connected via CircleCI GitHub App to a single CircleCI organization. + +If you attempt to connect your CircleCI organization to a GitHub organization that already has the CircleCI GitHub App installed (linked to a different CircleCI organization), you will be redirected to the GitHub App installation page and won't be redirected back to CircleCI. This can be confusing because GitHub will show a successful installation—but this refers to the existing connection to a different CircleCI organization, not the one you just tried to create. Unfortunately, GitHub doesn't indicate which CircleCI organization is already connected, so if you need help identifying the existing connection, you can submit a request link:https://forms.gle/dvcXN8ArByXqNNbJ7[by filling out this form]. + +#TODO Benny can you help with this section?# + +.GitHub settings showing the CircleCI App integration settings page. +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[Join Teammates on CircleCI] 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 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 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 a guide to renaming organizations and projects, see the xref:security:rename-organizations-and-repositories.adoc[Rename Organizations and Projects] page. + +== Delete and organization or project + +For a guide to 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: + +[.table-scroll] +-- +[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. +. Select 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 followers, CircleCI will consider it disabled and remove the associated keys. +* When you delete a CircleCI project, CircleCI will remove its associated keys. +**** + +When CircleCI builds your project, the private key is installed into the `.ssh` directory and SSH is subsequently configured to communicate with your version control provider. Therefore, the private key is used for: + +- Checking out the main project. +- Checking out any GitHub-hosted submodules. +- Checking out any GitHub-hosted private dependencies. +- Automatic git merging/tagging/etc. + +Private keys are also used to enable your project to check out additional private repositories. +-- +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 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 check out additional private repositories. +-- +GitLab:: ++ +-- +#TBC# +-- +Bitbucket Data Center:: ++ +-- +When you connect a repository with your CircleCI project, behind the scenes, CircleCI is registering a webhook within your Bitbucket Data Center project. You may verify this once you have successfully created the project by navigating to your repository's menu:Project Settings[Webhooks] page. +-- +==== + +=== Custom checkout commands + +CircleCI provides a `checkout` step that is used to check out your source code. You find 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 the VCS provider to a "known hosts" file (`~/.ssh/known_hosts`). Using `known_hosts` allows the executor to verify that the host it is connecting to is authentic. If you use the CircleCI `checkout` step, this is done automatically for you. + +[tabs] +==== +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 +``` +-- +GitLab self-managed:: ++ +-- +For GitLab self-managed instances, you need to add the SSH host keys to a "known hosts" file (`~/.ssh/known_hosts`). This enables CircleCI to verify that the host it is connecting to is authentic. The **known_hosts** input stores your instance's public host keys so CircleCI jobs can verify the remote host's identity when checking out code. + +SSH keys for remote servers can be fetched by running `ssh-keyscan `, for example, `ssh-keyscan test-gitlab.circleci.com`. + +When retrieving the host keys, you can confirm that you have the correct key by checking its fingerprints. You can check the fingerprints found in the **Instance Configuration** section of your self-managed instance's Help pages (link:https://gitlab.com/help/instance_configuration#ssh-host-keys-fingerprints[this Instance Configuration page] shows an example). +-- +==== + +#Do we need this step for people doing custom checkout for Bitbucket and GitLab.com?# + +== Best practices for SSH keys + +NOTE: This section is relevant to projects in a `github` or `bitbucket` type organization. + +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-user-key] +== Create a user key + +NOTE: If your organization is a `github` or `bitbucket` type organization, you can create a user key for your project. + +Create a user key in CircleCI when: + +* You need write access to your GitHub or Bitbucket repositories during your CI/CD pipeline. +* When you need to access multiple repositories that your user account has access to. + +Some example tasks where you might need a user key: + +* Pushing commits back to your repository. If your pipeline needs to commit and push changes back to GitHub (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. User keys are a bigger security risk if compromised. + +We recommend creating a dedicated "machine user" GitHub/Bitbucket account with minimal necessary permissions. THen add that machine user's key to CircleCI, rather than using your personal GitHub/Bitbucket account's key. + +To create a user key, follow these steps: + +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:[Add User Key]. +. You will see a warning that you should use a machine user. Select btn:[Confirm User]. +. You will now see your user key displayed on the page. + +[#user-key-security] +=== User key security + +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: + +[tabs] +==== +GitHub:: ++ +-- +In this example you will create a deploy key with write access to a GitHub repository. The GitHub repository is `https://github.com/you/test-repo`, and the CircleCI project is `https://app.circleci.com/pipelines/github/you/test-repo`. + +. Create an SSH key-pair by following the link:https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/[GitHub instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): ++ +[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. +-- +Bitbucket:: ++ +-- +In this example, the Bitbucket Cloud repository is `https://bitbucket.org/you/test-repo/src/main/`, and the CircleCI project is `https://app.circleci.com/pipelines/bitbucket/you/test-repo`. + +. Create an SSH key-pair by following the link:https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/[Bitbucket instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): ++ +```shell + ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +. Go to `https://bitbucket.org/you/test-repo/admin/access-keys/`, and select **Add key**. Enter a label in the "Label" field, then copy and paste the public key you created in step 1. Select **Add SSH key**. + +. Go to your project settings in the CircleCI app, select **SSH Keys**, and **Add SSH key**. In the "Hostname" field, enter `bitbucket.com` and add the private key you created in step 1. Then select **Add SSH Key**. + +. In your `.circleci/config.yml` file, add the fingerprint to a job using the `add_ssh_keys` key: ++ +```yaml + version: 2.1 + + jobs: + deploy-job: + steps: + - add_ssh_keys: + fingerprints: + - "SO:ME:FIN:G:ER:PR:IN:T" +``` + +When you push to your Bitbucket Cloud repository from a job, CircleCI will use the SSH key you added. +-- +GitLab:: ++ +-- +When creating a GitLab-based project in CircleCI, an SSH key is created, which is used to check out code from your repository. Each configuration you create generates a new SSH key to access the code in the repository associated with that configuration. At this time, only **Additional SSH Keys** are applicable to GitLab projects. + +. Create an SSH key-pair by following the link:https://docs.gitlab.com/ee/user/ssh.html[GitLab instructions]. When prompted to enter a passphrase, do **not** enter one (below is one example command to generate a key on macOS): ++ +```shell + ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +. Go to your project on link:https://gitlab.com/[GitLab] and navigate to **Settings > Repository**, and expand the **Deploy keys** section. Enter a title in the "Title" field, then copy and paste the public key you created in step 1. Check **Grant write permissions to this key** box, then select **Add key**. + +. Go to your project settings in the CircleCI app, select **SSH Keys**, and **Add SSH key**. In the "Hostname" field, enter `gitlab.com` and add the private key you created in step 1. Then select **Add SSH Key**. + +. In your `.circleci/config.yml` file, add the fingerprint to a job using the `add_ssh_keys` key: ++ +```yaml + version: 2.1 + + jobs: + deploy-job: + steps: + - add_ssh_keys: + fingerprints: + - "SO:ME:FIN:G:ER:PR:IN:T" +``` + +When you push to your GitLab repository from a job, CircleCI will use the SSH key you added. + +-- +==== + +For a guide to additional SSH keys for CircleCI pipelines, see the xref:integration:add-ssh-key.adoc[Add SSH Keys] page. + +== 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 the xref:guides:integration:using-the-circleci-github-app-in-an-oauth-org.adoc[Using the CircleCI GitHub App in an OAuth Organization] page. +* If the motivation is to **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 that is currently unsupported for GitHub App pipelines. For a matrix of feature support see the xref:integration:version-control-system-integration-overview.adoc[Version Control System Integration Overview] page. +* The following steps include *creating a new org*. If you need to transfer private orbs or self-hosted runner resource classes to your new org, contact link:https://support.circleci.com/[Support at CircleCI] before following step 14. +* If you have a dedicated account team at CircleCI, contact them first to discuss your migration. +==== + +. 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 contexts, you will need to recreate the contexts in your new organization. See the xref:security:contexts.adoc[Contexts] page for more information. +. Invite your teammates to the new organization (the one that is integrated with the CircleCI GitHub App) using the instructions on the xref:getting-started:invite-your-team.adoc[Join Teammates on CircleCI] 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# + +[#enable-project-to-check-out-additional-private-repositories] +=== How can I enable my project to check out additional private repositories? + +For `github` and `bitbucket` organizations, you can enable your project to check out additional private repositories by adding a _user_ key or additional SSH key to your project. See the <> section of this page for instructions. + +For `circleci`, `github` and `bitbucket` organizations, you can enable your project to check out additional private repositories by adding an _additional_ SSH key to your project. See the <> section of this page for instructions. + diff --git a/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc b/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc index 3f271b6747..cbd62d1767 100644 --- a/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc +++ b/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc @@ -88,7 +88,7 @@ NOTE: Only organization admins and project admins can delete projects. If you want to remove a project from your CircleCI account, follow the steps below. -CAUTION: Deleting a project will remove the complete build history. +CAUTION: Deleting a project will remove the complete build history. [tabs] ==== 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 3480e310a3..087b637d61 100644 --- a/docs/guides/modules/security/pages/rename-organizations-and-repositories.adoc +++ b/docs/guides/modules/security/pages/rename-organizations-and-repositories.adoc @@ -44,7 +44,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..55f934afd1 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. @@ -69,7 +71,7 @@ Go to **Project Settings > SSH Keys** to view SSH keys set up for your project. . Take note of the current key information to rotate. . Delete the user key by clicking the **X**. -. Add a new user key following the xref:integration:bitbucket-integration.adoc#create-a-bitbucket-user-key[Create a Bitbucket user key] instructions. +. Add a new user key following the xref:permissions-authentication:users-organizations-and-integrations-guide.adoc#create-a-user-key[Create a user key] instructions. . Go to Bitbucket’s user account settings to delete the matching public key. The Bitbucket URL is typically `https://bitbucket.org/account/settings/ssh-keys/`. The user names the keys, therefore, CircleCI does not know if the key name contains the string `CircleCI`. It is recommended to remove any key created before the rotation. [#rotate-an-additional-SSH-key-bitbucket] diff --git a/docs/guides/modules/test/pages/test-splitting-tutorial.adoc b/docs/guides/modules/test/pages/test-splitting-tutorial.adoc index 9c45c91ccf..ce1eb47b2c 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/configuration-reference.adoc b/docs/reference/modules/ROOT/pages/configuration-reference.adoc index c605e1088c..3f5070ce9a 100644 --- a/docs/reference/modules/ROOT/pages/configuration-reference.adoc +++ b/docs/reference/modules/ROOT/pages/configuration-reference.adoc @@ -2260,7 +2260,7 @@ NOTE: The lifetime of artifacts, workspaces, and caches can be customized on the [#add-ssh-keys] === *`add_ssh_keys`* -Special step that adds SSH keys from a project's settings to a container. Also configures SSH to use these keys. For more information on SSH keys see the xref:guides:integration:github-integration.adoc#create-additional-github-ssh-keys[Create additional GitHub SSH keys] page. +Special step that adds SSH keys from a project's settings to a container. Also configures SSH to use these keys. For more information on SSH keys see the xref:guides:integration:add-ssh-key.adoc[Add Additional SSH keys] page. CAUTION: *Using server?* only MD5 fingerprints are supported. In CircleCI in menu:Project Settings[SSH keys > Additional SSH keys] the MD5 fingerprint will be visible. SHA256 support is planned for an upcoming server release. 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 e5b793bf2b..907eb98b34 100644 --- a/docs/reference/modules/ROOT/pages/outbound-webhooks-reference.adoc +++ b/docs/reference/modules/ROOT/pages/outbound-webhooks-reference.adoc @@ -231,7 +231,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. [.table-scroll] -- @@ -287,7 +287,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]. [.table-scroll] -- @@ -354,7 +354,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 b5552e134e..c7848dd85d 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[]