diff --git a/changelogs/unreleased/docs-external-pull-request-pipelines.yml b/changelogs/unreleased/docs-external-pull-request-pipelines.yml new file mode 100644 index 0000000000000000000000000000000000000000..69a0cfdd8c8ce0b9460b189ccbdd63da5c7d538e --- /dev/null +++ b/changelogs/unreleased/docs-external-pull-request-pipelines.yml @@ -0,0 +1,5 @@ +--- +title: "Document `only/except: external_pull_requests`" +merge_request: 32969 +author: +type: added diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 02b8eb7daa7ed80e61c4ecb347f8d731ad76da7b..890068afc91bcaa199323d56a54f6bcab7378e3d 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -33,6 +33,72 @@ To connect to an external repository: ![CI/CD for external repository project creation](img/ci_cd_for_external_repo.png) +## Pipelines for external pull requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/65139) in GitLab Premium 12.3. + +When using GitLab CI/CD with an [external repository on GitHub](github_integration.md), +it's possible to run a pipeline in the context of a Pull Request. + +When you push changes to a remote branch in GitHub, GitLab CI/CD can run a pipeline for +the branch. However, when you open or update a Pull Request for that branch you may want to: + +- Run extra jobs. +- Not run specific jobs. + +For example: + +```yaml +always-run: + script: echo 'this should always run' + +on-pull-requests: + script: echo 'this should run on pull requests' + only: + - external_pull_requests + +except-pull-requests: + script: echo 'this should not run on pull requests' + except: + - external_pull_requests +``` + +### How it works + +When a repository is imported from GitHub, GitLab subscribes to webhooks +for `push` and `pull_request` events. Once a `pull_request` event is received, +the Pull Request data is stored and kept as a reference. If the Pull Request +has just been created, GitLab immediately creates a pipeline for the external +pull request. + +If changes are pushed to the branch referenced by the Pull Request and the +Pull Request is still open, a pipeline for the external pull request is +created. + +NOTE: **Note:** +GitLab CI/CD will create 2 pipelines in this case. One for the +branch push and one for the external pull request. + +Once the Pull Request is closed, no pipelines are created for the external pull +request, even if new changes are pushed to the same branch. + +### Additional predefined variables + +By using pipelines for external pull requests, GitLab exposes additional +[predefined variables](../variables/predefined_variables.md) to the pipeline jobs. + +The variable names are prefixed with `CI_EXTERNAL_PULL_REQUEST_`. + +### Limitations + +This feature currently does not support Pull Requests from fork repositories. Any Pull Requests from fork repositories will be ignored. [Read more](https://gitlab.com/gitlab-org/gitlab-ee/issues/5667). + +Given that GitLab will create 2 pipelines, if changes are pushed to a remote branch that +references an open Pull Request, both will contribute to the status of the Pull Request +via GitHub integration. If you want to exclusively run pipelines on external pull +requests and not on branches you can add `except: [branches]` to the job specs. +[Read more](https://gitlab.com/gitlab-org/gitlab-ee/issues/24089#workaround). + [ee-4642]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4642 [eep]: https://about.gitlab.com/pricing/ [mirroring]: ../../workflow/repository_mirroring.md diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index a3c253cc517f07dd59b375a24c8d2c417fd1ec7a..96cc143734e9f64ea45e7fe6af7088c24b0786bc 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -60,16 +60,21 @@ future GitLab releases.** | `CI_MERGE_REQUEST_PROJECT_URL` | 11.6 | all | The URL of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `http://192.168.10.15:3000/namespace/awesome-project`). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_REF_PATH` | 11.6 | all | The ref path of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). (e.g. `refs/merge-requests/1/head`). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` | 11.6 | all | The source branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | -| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | 11.9 | all | The HEAD sha of the source branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the source branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_ID` | 11.6 | all | The ID of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` | 11.6 | all | The path of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_URL` | 11.6 | all | The URL of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | 11.6 | all | The target branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | -| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD sha of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_TITLE` | 11.9 | all | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_MILESTONE` | 11.9 | all | The milestone title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_LABELS` | 11.9 | all | Comma-separated label names of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_EXTERNAL_PULL_REQUEST_IID` | 12.3 | all | Pull Request ID from GitHub if the [pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open. | +| `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA` | 12.3 | all | The HEAD SHA of the source branch of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open. | +| `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA` | 12.3 | all | The HEAD SHA of the target branch of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open. | +| `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME` | 12.3 | all | The source branch name of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open. | +| `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME` | 12.3 | all | The target branch name of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open. | | `CI_NODE_INDEX` | 11.5 | all | Index of the job in the job set. If the job is not parallelized, this variable is not set. | | `CI_NODE_TOTAL` | 11.5 | all | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`. | | `CI_API_V4_URL` | 11.7 | all | The GitLab API v4 root URL | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 03b053b9be3e0814bc69934e302375143a6ee146..878940493f3c2c6041006a6f0b632f5258160032 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -388,6 +388,7 @@ In addition, `only` and `except` allow the use of special keywords: | `triggers` | For pipelines created using a trigger token. | | `web` | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). | | `merge_requests` | When a merge request is created or updated (See [pipelines for merge requests](../merge_request_pipelines/index.md)). | +| `external_pull_requests`| When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md##pipelines-for-external-pull-requests)). | | `chat` | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. | In the example below, `job` will run only for refs that start with `issue-`,