diff options
Diffstat (limited to 'doc/ci/ci_cd_for_external_repos')
| -rw-r--r-- | doc/ci/ci_cd_for_external_repos/bitbucket_integration.md | 49 | ||||
| -rw-r--r-- | doc/ci/ci_cd_for_external_repos/github_integration.md | 49 | ||||
| -rw-r--r-- | doc/ci/ci_cd_for_external_repos/index.md | 24 |
3 files changed, 86 insertions, 36 deletions
diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index 1c8e12d229c..9126eb65f07 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -1,8 +1,15 @@ +--- +type: howto +--- + # Using GitLab CI/CD with a Bitbucket Cloud repository **[PREMIUM]** -GitLab CI/CD can be used with Bitbucket Cloud by creating a -[CI/CD project](https://docs.gitlab.com/ee/user/project/ci_cd_for_external_repo.html) and connecting -your Git repository via URL. +GitLab CI/CD can be used with Bitbucket Cloud by: + +1. Creating a [CI/CD project](https://docs.gitlab.com/ee/user/project/ci_cd_for_external_repo.html). +1. Connecting your Git repository via URL. + +To use GitLab CI/CD with a Bitbucket Cloud repository: 1. In GitLab create a **CI/CD for external repo**, select **Repo by URL** and create the project. @@ -16,13 +23,13 @@ your Git repository via URL. with `api` scope. This will be used to authenticate requests from the web hook that will be created in Bitbucket to notify GitLab of new commits. -1. In Bitbucket from **Settings > Webhooks** create a new web hook to notify +1. In Bitbucket, from **Settings > Webhooks**, create a new web hook to notify GitLab of new commits. The web hook URL should be set to the GitLab API to trigger pull mirroring, using the Personal Access Token we just generated for authentication. - ``` + ```text https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN> ``` @@ -33,27 +40,27 @@ your Git repository via URL. After saving, test the web hook by pushing a change to your Bitbucket repository. -1. In Bitbucket create an **App Password** from **Bitbucket Settings > App +1. In Bitbucket, create an **App Password** from **Bitbucket Settings > App Passwords** to authenticate the build status script setting commit build statuses in Bitbucket. Repository write permissions are required.  -1. In GitLab from **Settings > CI/CD > Environment variables** add variables to allow - communication with Bitbucket via the Bitbucket API. +1. In GitLab, from **Settings > CI/CD > Environment variables**, add variables to allow + communication with Bitbucket via the Bitbucket API: - `BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above + `BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above. - `BITBUCKET_USERNAME`: the username of the Bitbucket account + `BITBUCKET_USERNAME`: the username of the Bitbucket account. - `BITBUCKET_NAMESPACE`: set this if your GitLab and Bitbucket namespaces differ + `BITBUCKET_NAMESPACE`: set this if your GitLab and Bitbucket namespaces differ. - `BITBUCKET_REPOSITORY`: set this if your GitLab and Bitbucket project names differ + `BITBUCKET_REPOSITORY`: set this if your GitLab and Bitbucket project names differ. -1. In Bitbucket add a script to push the pipeline status to Bitbucket. +1. In Bitbucket, add a script to push the pipeline status to Bitbucket. > Note: changes made in GitLab will be overwritten by any changes made - upstream in Bitbucket. + > upstream in Bitbucket. Create a file `build_status` and insert the script below and run `chmod +x build_status` in your terminal to make the script executable. @@ -111,7 +118,7 @@ your Git repository via URL. 1. Still in Bitbucket, create a `.gitlab-ci.yml` file to use the script to push pipeline success and failures to Bitbucket. - ``` + ```yaml stages: - test - ci_status @@ -145,3 +152,15 @@ GitLab is now configured to mirror changes from Bitbucket, run CI/CD pipelines configured in `.gitlab-ci.yml` and push the status to Bitbucket. [pull-mirroring]: ../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index 0e2acf957e0..612dcc93bc1 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -1,3 +1,7 @@ +--- +type: howto +--- + # Using GitLab CI/CD with a GitHub repository **[PREMIUM]** GitLab CI/CD can be used with **GitHub.com** and **GitHub Enterprise** by @@ -15,7 +19,7 @@ administrator: NOTE: **Note:** Due to a 10-token limitation on the [GitHub OAuth Implementation](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#creating-multiple-tokens-for-oauth-apps), -if you import more than 10 times, your oldest imported project's token will be +if you import more than 10 times, your oldest imported project's token will be revoked. See issue [#9147](https://gitlab.com/gitlab-org/gitlab-ee/issues/9147) for more information. @@ -31,23 +35,27 @@ for more information. 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). -GitLab will import the project, enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter), enable -[GitHub project integration](https://docs.gitlab.com/ee/user/project/integrations/github.html), and create a web hook -on GitHub to notify GitLab of new commits. +GitLab will: + +1. Import the project. +1. Enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter). +1. Enable [GitHub project integration](https://docs.gitlab.com/ee/user/project/integrations/github.html). +1. Create a web hook on GitHub to notify GitLab of new commits. ## Connect with Personal Access Token -NOTE: **Note:** Personal access tokens can only be used to connect GitHub.com +NOTE: **Note:** +Personal access tokens can only be used to connect GitHub.com repositories to GitLab. If you are not using the [GitHub integration](../../integration/github.md), you can still perform a one-off authorization with GitHub to grant GitLab access your repositories: -1. Open https://github.com/settings/tokens/new to create a **Personal Access +1. Open <https://github.com/settings/tokens/new> to create a **Personal Access Token**. This token with be used to access your repository and push commit statuses to GitHub. - + The `repo` and `admin:repo_hook` should be enable to allow GitLab access to your project, update commit statuses, and create a web hook to notify GitLab of new commits. @@ -62,20 +70,23 @@ repositories: 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). -GitLab will import the project, enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter), enable -[GitHub project integration](https://docs.gitlab.com/ee/user/project/integrations/github.html), and create a web hook -on GitHub to notify GitLab of new commits. +GitLab will: + +1. Import the project. +1. Enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter). +1. Enable [GitHub project integration](https://docs.gitlab.com/ee/user/project/integrations/github.html). +1. Create a web hook on GitHub to notify GitLab of new commits. ## Connect manually If the [GitHub integration](../../integration/github.md) is not enabled, or is enabled for a different GitHub instance, you GitLab CI/CD can be manually enabled for -your repository. +your repository: -1. In GitHub open https://github.com/settings/tokens/new create a **Personal +1. In GitHub open <https://github.com/settings/tokens/new> create a **Personal Access Token.** GitLab will use this token to access your repository and push commit statuses. - + Enter a **Token description** and update the scope to allow: `repo` so that GitLab can access your project and update commit statuses @@ -109,3 +120,15 @@ your repository.  1. In GitHub add a `.gitlab-ci.yml` to configure GitLab CI/CD. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 450ffe512dc..5de88412121 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -1,3 +1,7 @@ +--- +type: index, howto +--- + # GitLab CI/CD for external repositories **[PREMIUM]** NOTE: **Note:** @@ -6,22 +10,26 @@ GitLab.com users until September 22nd, 2019. >[Introduced][ee-4642] in [GitLab Premium][eep] 10.6. -GitLab CI/CD can be used with GitHub or any other Git server. +GitLab CI/CD can be used with: + +- [GitHub](github_integration.md). +- [Bitbucket Cloud](bitbucket_integration.md). +- Any other Git server. + Instead of moving your entire project to GitLab, you can connect your external repository to get the benefits of GitLab CI/CD. -- [GitHub](github_integration.md) -- [Bitbucket Cloud](bitbucket_integration.md) - Connecting an external repository will set up [repository mirroring][mirroring] and create a lightweight project where issues, merge requests, wiki, and snippets disabled. These features [can be re-enabled later][settings]. -1. From your GitLab dashboard click **New project** -1. Switch to the **CI/CD for external repo** tab -1. Choose **GitHub** or **Repo by URL** -1. The next steps are similar to the [import flow](../../user/project/import/index.md) +To connect to an external repository: + +1. From your GitLab dashboard, click **New project**. +1. Switch to the **CI/CD for external repo** tab. +1. Choose **GitHub** or **Repo by URL**. +1. The next steps are similar to the [import flow](../../user/project/import/index.md).  |