Commit 0f74c337 authored by James Lopez's avatar James Lopez

Merge branch 'jyavorska-master-patch-24279' into 'master'

Add templates for use with rules keyword

Closes #217732

See merge request gitlab-org/gitlab!32070
parents 16561244 e2915da8
...@@ -37,79 +37,23 @@ To enable pipelines for merge requests: ...@@ -37,79 +37,23 @@ To enable pipelines for merge requests:
## Configuring pipelines for merge requests ## Configuring pipelines for merge requests
To configure pipelines for merge requests, configure your [CI/CD configuration file](../yaml/README.md). To configure pipelines for merge requests you need to configure your [CI/CD configuration file](../yaml/README.md).
There are a few different ways to do this. There are a few different ways to do this:
### Enable pipelines for merge requests for all jobs ### Use `rules` to run pipelines for merge requests
The recommended method for enabling pipelines for merge requests for all jobs in When using `rules`, which is the preferred method, we recommend starting with one
a pipeline is to use [`workflow:rules`](../yaml/README.md#workflowrules). of the [`workflow:rules` templates](../yaml/README.md#workflowrules-templates) to ensure
your basic configuration is correct. Instructions on how to do this, as well as how
In this example, the pipeline always runs for all merge requests, as well as for all changes to customize, are available at that link.
to the master branch:
```yaml
workflow:
rules:
- if: $CI_MERGE_REQUEST_ID # Execute jobs in merge request context
- if: $CI_COMMIT_BRANCH == 'master' # Execute jobs when a new commit is pushed to master branch
build:
stage: build
script: ./build
test:
stage: test
script: ./test
deploy:
stage: deploy
script: ./deploy
```
### Enable pipelines for merge requests for specific jobs
To enable pipelines for merge requests for specific jobs, you can use
[`rules`](../yaml/README.md#rules).
In the following example:
- The `build` job runs for all changes to the `master` branch, as well as for all merge requests.
- The `test` job runs for all merge requests.
- The `deploy` job runs for all changes to the `master` branch, but does *not* run
for merge requests.
```yaml
build:
stage: build
script: ./build
rules:
- if: $CI_COMMIT_BRANCH == 'master' # Execute jobs when a new commit is pushed to master branch
- if: $CI_MERGE_REQUEST_ID # Execute jobs in merge request context
test:
stage: test
script: ./test
rules:
- if: $CI_MERGE_REQUEST_ID # Execute jobs in merge request context
deploy:
stage: deploy
script: ./deploy
rules:
- if: $CI_COMMIT_BRANCH == 'master' # Execute jobs when a new commit is pushed to master branch
```
### Use `only` or `except` to run pipelines for merge requests ### Use `only` or `except` to run pipelines for merge requests
NOTE: **Note**: If you want to continue using `only/except`, this is possible but please review the drawbacks
The [`only` / `except`](../yaml/README.md#onlyexcept-basic) keywords are going to be deprecated below.
and you should not use them.
To enable pipelines for merge requests, you can use `only / except`. When you use this method,
you have to specify `only: - merge_requests` for each job.
In this example, the pipeline contains a `test` job that is configured to run on merge requests. When you use this method, you have to specify `only: - merge_requests` for each job. In this
example, the pipeline contains a `test` job that is configured to run on merge requests.
The `build` and `deploy` jobs don't have the `only: - merge_requests` parameter, The `build` and `deploy` jobs don't have the `only: - merge_requests` parameter,
so they will not run on merge requests. so they will not run on merge requests.
...@@ -259,60 +203,16 @@ The variable names begin with the `CI_MERGE_REQUEST_` prefix. ...@@ -259,60 +203,16 @@ The variable names begin with the `CI_MERGE_REQUEST_` prefix.
### Two pipelines created when pushing to a merge request ### Two pipelines created when pushing to a merge request
If two pipelines are created when you push a new change to a merge request, If you are experiencing duplicated pipelines when using `rules`, take a look at
check your CI configuration file. the [key details when using `rules`](../yaml/README.md#key-details-when-using-rules),
which will help you get your starting configuration correct.
For example, with this `.gitlab-ci.yml` configuration:
```yaml
test:
script: ./test
rules:
- if: $CI_MERGE_REQUEST_ID # Include this job in pipelines for merge request
- if: $CI_COMMIT_BRANCH # Include this job in all branch pipelines
# Or, if you are using the `only:` keyword:
# only:
# - merge_requests
# - branches
```
Two pipelines are created when you push a commit to a branch that also has a pending
merge request:
- A merge request pipeline that runs for the changes in the merge request. In
**CI/CD > Pipelines**, the merge request icon (**{merge-request}**)
and the merge request ID are displayed. If you hover over the ID, the merge request name is displayed.
![MR pipeline icon example](img/merge_request_pipelines_doubled_MR_v12_09.png)
- A "branch" pipeline that runs for the commit pushed to the branch. In **CI/CD > Pipelines**,
the branch icon (**{branch}**) and branch name are displayed. This pipeline is
created even if no merge request exists.
![branch pipeline icon example](img/merge_request_pipelines_doubled_branch_v12_09.png)
With the example configuration above, there is overlap between these two events.
When you push a commit to a branch that also has an open merge request pending,
both types of pipelines are created.
To fix this overlap, you must explicitly define which job should run for which
purpose, for example:
```yaml
test:
script: ./test
rules:
- if: $CI_MERGE_REQUEST_ID # Include this job in pipelines for merge request
- if: $CI_COMMIT_BRANCH == 'master' # Include this job in master branch pipelines
```
Similar `rules:` should be added to all jobs to avoid any overlapping pipelines. Alternatively, If you are seeing two pipelines when using `only/except`, please see the caveats
you can use the [`workflow:`](../yaml/README.md#exclude-jobs-with-rules-from-certain-pipelines) related to using `only/except` above (or, consider moving to `rules`).
parameter to add the same rules to all jobs globally.
### Two pipelines created when pushing an invalid CI configuration file ### Two pipelines created when pushing an invalid CI configuration file
Similar to above, pushing to a branch with an invalid CI configuration file can trigger Pushing to a branch with an invalid CI configuration file can trigger
the creation of two types of failed pipelines. One pipeline is a failed merge request the creation of two types of failed pipelines. One pipeline is a failed merge request
pipeline, and the other is a failed branch pipeline, but both are caused by the same pipeline, and the other is a failed branch pipeline, but both are caused by the same
invalid configuration. invalid configuration.
......
...@@ -286,7 +286,45 @@ determine whether or not a pipeline is created. It currently accepts a single ...@@ -286,7 +286,45 @@ determine whether or not a pipeline is created. It currently accepts a single
`rules:` key that operates similarly to [`rules:` defined within jobs](#rules), `rules:` key that operates similarly to [`rules:` defined within jobs](#rules),
enabling dynamic configuration of the pipeline. enabling dynamic configuration of the pipeline.
The configuration options currently available for `workflow:rules` are:​ #### `workflow:rules` templates
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0.
We provide pre-made templates for use with your pipelines that set up `workflow: rules`
for common scenarios. Usage of these will make things easier and prevent duplicate pipelines from running.
The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)
makes your pipelines run for branches and tags.
Branch pipeline status will be displayed within merge requests that use that branch
as a source, but this pipeline type does not support any features offered by
[Merge Request Pipelines](../merge_request_pipelines/) like
[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results-premium)
or [Merge Trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/).
Use this template if you are intentionally avoiding those features.
It is [included](#include) as follows:
```yaml
include:
- template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'
```
The [`MergeRequest-Pipelines` include](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml) sets your pipelines to run for the default branch (usually `master`), tags, and
The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml)
makes your pipelines run for the default branch (usually `master`), tags, and
all types of merge request pipelines. Use this template if you use any of the
the [Pipelines for Merge Requests features](../merge_request_pipelines/), as mentioned
above.
It is [included](#include) as follows:
```yaml
include:
- template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'
```
If you prefer to define your own rules, the configuration options currently available are:​
- [`if`](#rulesif): Define a rule. - [`if`](#rulesif): Define a rule.
- [`when`](#when): May be set to `always` or `never` only. If not provided, the default value is `always`​. - [`when`](#when): May be set to `always` or `never` only. If not provided, the default value is `always`​.
...@@ -858,10 +896,26 @@ the `.template` job, and uses the `alpine` Docker image as defined in the local ...@@ -858,10 +896,26 @@ the `.template` job, and uses the `alpine` Docker image as defined in the local
`rules` allows for a list of individual rule objects to be evaluated `rules` allows for a list of individual rule objects to be evaluated
*in order*, until one matches and dynamically provides attributes to the job. *in order*, until one matches and dynamically provides attributes to the job.
Note that `rules` can't be used in combination with `only/except` since it's intended
to replace that functionality. If you attempt to do this the linter will return a CAUTION: **Caution:**
`rules` can't be used in combination with `only/except` as it is a replacement for that functionality. If you attempt to do this, the linter will return a
`key may not be used with rules` error. `key may not be used with rules` error.
#### Key details when using `rules`
A very important difference between `rules` and `only/except`, is that jobs defined
with `rules` trigger merge request pipelines by default, but `only/except` jobs do not.
This may be surprising if migrating from `only` and `except`, so new users of `rules`
can use one of the [`workflow: rules` templates](#workflowrules-templates) to get started.
This will ensure that the behavior is more stable as you start adding additional `rules`
blocks, and will avoid issues like creating a duplicate, merge request (detached) pipeline.
We don't recomment mixing `only/except` jobs with `rules` jobs in the same pipeline.
It may not cause YAML errors, but debugging the exact execution behavior can be complex
due to the different default behaviors of `only/except` and `rules`.
### Rules clauses
Available rule clauses include: Available rule clauses include:
- [`if`](#rulesif) (similar to [`only:variables`](#onlyvariablesexceptvariables)) - [`if`](#rulesif) (similar to [`only:variables`](#onlyvariablesexceptvariables))
...@@ -995,47 +1049,6 @@ job: ...@@ -995,47 +1049,6 @@ job:
In this example, if the first rule matches, then the job will have `when: manual` and `allow_failure: true`. In this example, if the first rule matches, then the job will have `when: manual` and `allow_failure: true`.
#### Exclude jobs with `rules:` from certain pipelines
Jobs with `rules:` can cause two pipelines to be created unexpectedly:
- One pipeline from pushing a commit to a branch.
- A second ["detached" pipeline for a merge request](../merge_request_pipelines/index.md).
`only` and `except` jobs don't trigger merge request pipelines by default, but this
is not the case for jobs with `rules:`, which may be surprising if migrating from `only`
and `except` to `rules:`.
If you're using `rules:` and you see two pipelines for commits to branches that have
a merge request, you have two options:
- Individually exclude each job that uses `rules:` from merge request pipelines. The
example below will cause the job to **not** run in *pipelines for merge requests*,
but it **will** run in pipelines for *new tags and pipelines running on branch refs*:
```yaml
job:
rules:
- if: $CI_MERGE_REQUEST_ID
when: never
- when: manual
script:
- echo hello
```
- Add a global [`workflow: rules`](#workflowrules) to allow pipelines in only certain
situations. The example below will only run pipelines for merge requests, new tags and
changes to master. It will **not** run any pipelines *on any branch except master*, but
it will run **detached merge request pipelines** for any merge request, targeting any branch:
```yaml
workflow:
rules:
- if: $CI_MERGE_REQUEST_ID
- if: $CI_COMMIT_TAG
- if: $CI_COMMIT_BRANCH == "master"
```
#### Complex rule clauses #### Complex rule clauses
To conjoin `if`, `changes`, and `exists` clauses with an AND, use them in the To conjoin `if`, `changes`, and `exists` clauses with an AND, use them in the
......
# Read more on when to use this template at
# https://docs.gitlab.com/ee/ci/yaml/#workflowrules
workflow:
rules:
- if: $CI_COMMIT_TAG
- if: $CI_COMMIT_BRANCH
# Read more on when to use this template at
# https://docs.gitlab.com/ee/ci/yaml/#workflowrules
workflow:
rules:
- if: $CI_MERGE_REQUEST_IID
- if: $CI_COMMIT_TAG
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment