From 4b2875a000342da7ea5b4f174bb6104aaf72f3fc Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Fri, 7 Dec 2018 14:50:54 +0900 Subject: Documentation for merge request pipelines This is a documentation change about #15310. --- .../merge_request_pipelines/img/merge_request.png | Bin 0 -> 57512 bytes .../img/pipeline_detail.png | Bin 0 -> 42583 bytes doc/ci/merge_request_pipelines/index.md | 84 +++++++++++++++++++++ 3 files changed, 84 insertions(+) create mode 100644 doc/ci/merge_request_pipelines/img/merge_request.png create mode 100644 doc/ci/merge_request_pipelines/img/pipeline_detail.png create mode 100644 doc/ci/merge_request_pipelines/index.md (limited to 'doc/ci/merge_request_pipelines') diff --git a/doc/ci/merge_request_pipelines/img/merge_request.png b/doc/ci/merge_request_pipelines/img/merge_request.png new file mode 100644 index 00000000000..1fe2eec2008 Binary files /dev/null and b/doc/ci/merge_request_pipelines/img/merge_request.png differ diff --git a/doc/ci/merge_request_pipelines/img/pipeline_detail.png b/doc/ci/merge_request_pipelines/img/pipeline_detail.png new file mode 100644 index 00000000000..def1781dd75 Binary files /dev/null and b/doc/ci/merge_request_pipelines/img/pipeline_detail.png differ diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md new file mode 100644 index 00000000000..6697bf9480f --- /dev/null +++ b/doc/ci/merge_request_pipelines/index.md @@ -0,0 +1,84 @@ +# Pipelines for merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6 + +Usually, when a developer creates a new merge request, a pipeline runs on the +new change and checks if it's qualified to be merged into a target branch. This +pipeline should contain only necessary jobs for checking the new changes. +For example, unit tests, lint checks, and Review Apps are often used in this cycle. + +With pipelines for merge requests, you can design a specific pipeline structure +for merge requests. All you need to do is just adding `only: [merge_requests]` to +the jobs that you want it to run for only merge requests. +Every time, when developers create or update merge requests, a pipeline runs on +their new commits at every push to GitLab. + +NOTE: **Note**: +If you use both this feature and the [Merge When Pipeline Succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md) +feature, pipelines for merge requests take precendence over the other regular pipelines. + +For example, consider a GitLab CI/CD configuration in .gitlab-ci.yml as follows: + +```yaml +build: + stage: build + script: ./build + only: + - branches + - tags + - merge_requests + +test: + stage: test + script: ./test + only: + - merge_requests + +deploy: + stage: deploy + script: ./deploy +``` + +After a developer updated code in a merge request with whatever methods (e.g. `git push`), +GitLab detects that the code is updated and create a new pipeline for the merge request. +The pipeline fetches the latest code from the source branch and run tests against it. +In this example, the pipeline contains only `build` and `test` jobs. +Since `deploy` job does not have the `only: [merge_requests]` rule, +deployment jobs will not happen in the merge request. + +Consider this pipeline list viewed from the **Pipelines** tab in a merge request: + +![Merge request page](img/merge_request.png) + +Note that pipelines tagged as **merge request** indicate that they were triggered +when a merge request was created or updated. + +The same tag is shown on the pipeline's details: + +![Pipeline's details](img/pipeline_detail.png) + +## Important notes about merge requests from forked projects + +Note that the current behavior is subject to change. In the usual contribution +flow, external contributors follow the following steps: + +1. Fork a parent project. +1. Create a merge request from the forked project that targets the `master` branch +in the parent project. +1. A pipeline runs on the merge request. +1. A mainatiner from the parent project checks the pipeline result, and merge +into a target branch if the latest pipeline has passed. + +Currently, those pipelines are created in a **forked** project, not in the +parent project. This means you cannot completely trust the pipeline result, +because, technically, external contributors can disguise their pipeline results +by tweaking their GitLab Runner in the forked project. + +There are multiple reasons about why GitLab doesn't allow those pipelines to be +created in the parent project, but one of the biggest reasons is security. +External users could steal secret variables from the parent project by modifying +.gitlab-ci.yml. + +We're discussing a secure solution about how to run pipelines for merge requests +that submitted from forked projects, +see [the issue about the permission extension](https://gitlab.com/gitlab-org/gitlab-ce/issues/23902). -- cgit v1.2.3