Document pipelines for external pull requestsdocs-external-pull-request-pipelines

Describe how the GitHub integration leverages
the new feature and how to select which jobs
to run in the context of a pull request
pipeline using `only/except: external_pull_request`

4 files changed, 79 insertions, 2 deletions

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 00000000000..69a0cfdd8c8
--- /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 02b8eb7daa7..890068afc91 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 a3c253cc517..96cc143734e 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 03b053b9be3..878940493f3 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-`,