diff options
Diffstat (limited to 'doc/ci')
23 files changed, 264 insertions, 89 deletions
diff --git a/doc/ci/README.md b/doc/ci/README.md index ca9d0aa61bd..90d0e6a7dc6 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -131,7 +131,7 @@ Its feature set is listed on the table below according to DevOps stages. | **Secure** || | [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities.| | [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | -| [License Management](../user/application_security/license_management/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | +| [License Compliance](../user/application_security/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | | [Security Test reports](../user/project/merge_requests/index.md#security-reports-ultimate) **(ULTIMATE)** | Check for app vulnerabilities. | ## Examples @@ -174,7 +174,7 @@ been necessary. These are: #### 12.0 -- [Use refspec to clone/fetch git +- [Use refspec to clone/fetch Git repository](https://gitlab.com/gitlab-org/gitlab-runner/issues/4069). - [Old cache configuration](https://gitlab.com/gitlab-org/gitlab-runner/issues/4070). diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index f8151e3e18c..ab9fa517e23 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -172,6 +172,29 @@ job: cache: {} ``` +### Inherit global config, but override specific settings per job + +You can override cache settings without overwriting the global cache by using +[anchors](../yaml/README.md#anchors). For example, if you want to override the +`policy` for one job: + +```yaml +cache: &global_cache + key: ${CI_COMMIT_REF_SLUG} + paths: + - node_modules/ + - public/ + - vendor/ + policy: pull-push + +job: + cache: + # inherit all global cache settings + <<: *global_cache + # override the policy + policy: pull +``` + For more fine tuning, read also about the [`cache: policy`](../yaml/README.md#cachepolicy). 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 f639e3dadee..fa56503072d 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -11,35 +11,10 @@ GitLab. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a video on [Using GitLab CI/CD pipelines with GitHub repositories](https://www.youtube.com/watch?v=qgl3F2j-1cI). -## Connect with GitHub integration - -If the [GitHub integration](../../integration/github.md) has been enabled by your GitLab -administrator: - -1. In GitLab create a **CI/CD for external repo** project and select - **GitHub**. - -  - -1. Once authenticated, you will be redirected to a list of your repositories to - connect. Click **Connect** to select the repository. - -  - -1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). - -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](../../user/project/integrations/github.md). -1. Create a web hook on GitHub to notify GitLab of new commits. - -CAUTION: **Caution:** -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 -revoked. See issue [#9147](https://gitlab.com/gitlab-org/gitlab-ee/issues/9147) -for more information. +NOTE: **Note:** +Because of [GitHub limitations](https://gitlab.com/gitlab-org/gitlab-ee/issues/9147), +[GitHub OAuth](../../integration/github.html#enabling-github-oauth) +cannot be used to authenticate with GitHub as an external CI/CD repository. ## Connect with Personal Access Token @@ -47,8 +22,7 @@ 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 +To 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 @@ -69,18 +43,19 @@ 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](../../user/project/integrations/github.md), 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](../../user/project/integrations/github.md) +1. Create a web hook on GitHub to notify GitLab of new commits. ## Connect manually NOTE: **Note:** -To use **GitHub Enterprise** with **GitLab.com** use this method. +To use **GitHub Enterprise** with **GitLab.com**, use this method. -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: +To manually enable GitLab CI/CD for your repository: 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 diff --git a/doc/ci/ci_cd_for_external_repos/img/github_repo_list.png b/doc/ci/ci_cd_for_external_repos/img/github_repo_list.png Binary files differdeleted file mode 100644 index 73579dd3cf1..00000000000 --- a/doc/ci/ci_cd_for_external_repos/img/github_repo_list.png +++ /dev/null diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index e54be9f3bd9..60e3120ba33 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -36,7 +36,7 @@ It has a pipeline that looks like the following: | ----- | ---- | ------ | | build_a | test_a | deploy_a | | build_b | test_b | deploy_b | -| build_c | test_c | deploy_c | +| build_c | test_c | deploy_c | | build_d | test_d | deploy_d | Using a DAG, you can relate the `_a` jobs to each other separately from the `_b` jobs, @@ -65,7 +65,7 @@ as quickly as possible. Relationships are defined between jobs using the [`needs:` keyword](../yaml/README.md#needs). Note that `needs:` also works with the [parallel](../yaml/README.md#parallel) keyword, -giving your powerful options for parallelization within your pipeline. +giving you powerful options for parallelization within your pipeline. ## Limitations diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 2cbad5f101c..7c173970324 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -575,6 +575,42 @@ For private and internal projects: docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` +### Using docker-in-docker image from Container Registry + +If you want to use your own Docker images for docker-in-docker there are a few things you need to do in addition to the steps in the [docker-in-docker](#use-docker-in-docker-workflow-with-docker-executor) section: + +1. Update the `image` and `service` to point to your registry. +1. Add a service [alias](https://docs.gitlab.com/ee/ci/yaml/#servicesalias) + +Below is an example of how your `.gitlab-ci.yml` should look like, assuming you have it configured with [TLS enabled](#tls-enabled): + +```yaml + build: + image: $CI_REGISTRY/group/project/docker:19.03.1 + services: + - name: $CI_REGISTRY/group/project/docker:19.03.1-dind + alias: docker + variables: + # Specify to Docker where to create the certificates, Docker will + # create them automatically on boot, and will create + # `/certs/client` that will be shared between the service and + # build container. + DOCKER_TLS_CERTDIR: "/certs" + DOCKER_DRIVER: overlay2 + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` + +If you forget to set the service alias the `docker:19.03.1` image won't find the +`dind` service, and an error like the following is thrown: + +```sh +$ docker info +error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host +``` + ### Container Registry examples If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml` diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index d5056568dff..489791141ed 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -495,14 +495,6 @@ that runner. ## Define an image from a private Container Registry -> **Notes:** -> -> - This feature requires GitLab Runner **1.8** or higher -> - For GitLab Runner versions **>= 0.6, <1.8** there was a partial -> support for using private registries, which required manual configuration -> of credentials on runner's host. We recommend to upgrade your Runner to -> at least version **1.8** if you want to use private registries. - To access private container registries, the GitLab Runner process can use: - [Statically defined credentials](#using-statically-defined-credentials). That is, a username and password for a specific registry. @@ -525,6 +517,17 @@ it's provided as an environment variable. This is because GitLab Runnner uses ** `config.toml` configuration and doesn't interpolate **ANY** environment variables at runtime. +### Requirements and limitations + +- This feature requires GitLab Runner **1.8** or higher. +- For GitLab Runner versions **>= 0.6, <1.8** there was a partial + support for using private registries, which required manual configuration + of credentials on runner's host. We recommend to upgrade your Runner to + at least version **1.8** if you want to use private registries. +- Not available for [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html), + follow <https://gitlab.com/gitlab-org/gitlab-runner/issues/2673> for + details. + ### Using statically-defined credentials There are two approaches that you can take in order to access a diff --git a/doc/ci/examples/license_management.md b/doc/ci/examples/license_management.md index 53e38111bf3..0d12c9a20f2 100644 --- a/doc/ci/examples/license_management.md +++ b/doc/ci/examples/license_management.md @@ -1,5 +1,5 @@ --- -redirect_to: '../../user/application_security/license_management/index.md' +redirect_to: '../../user/application_security/license_compliance/index.md' --- -This document was moved to [another location](../../user/application_security/license_management/index.md). +This document was moved to [another location](../../user/application_security/license_compliance/index.md). diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index f8a3fab88e3..ace1204511e 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -32,7 +32,7 @@ There are some high level differences between the products worth mentioning: ## Groovy vs. YAML -Jenkins Pipelines are based on [Groovy](https://groovy-lang.org/), so the pipeline specification is written as code. +Jenkins Pipelines are based on [Groovy](https://groovy-lang.org/), so the pipeline specification is written as code. GitLab works a bit differently, we use the more highly structured [YAML](https://yaml.org/) format, which places scripting elements inside of `script:` blocks separate from the pipeline specification itself. @@ -56,7 +56,7 @@ rspec: - .in-docker script: - rake rspec -``` +``` ## Artifact publishing @@ -143,7 +143,7 @@ default: GitLab CI also lets you define stages, but is a little bit more free-form to configure. The GitLab [`stages` keyword](../yaml/README.md#stages) is a top level setting that enumerates the list of stages, but you are not required to nest individual jobs underneath -the `stages` section. Any job defined in the `.gitlab-ci.yml` can be made a part of any stage through use of the +the `stages` section. Any job defined in the `.gitlab-ci.yml` can be made a part of any stage through use of the [`stage:` keyword](../yaml/README.md#stage). Note that, unless otherwise specified, every pipeline is instantiated with a `build`, `test`, and `deploy` stage @@ -229,4 +229,4 @@ our very powerful [`only/except` rules system](../yaml/README.md#onlyexcept-basi ```yaml my_job: only: branches -```
\ No newline at end of file +``` diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index ad07c662965..126e12e460f 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -35,10 +35,9 @@ get out of WIP status or resolve merge conflicts as soon as possible. ## Requirements and limitations -Pipelines for merged results require: +Pipelines for merged results require a [GitLab Runner][runner] 11.9 or newer. -- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. -- [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. +[runner]: https://gitlab.com/gitlab-org/gitlab-runner In addition, pipelines for merged results have the following limitations: diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md index 80a1c264bc4..7998b0452be 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -141,4 +141,4 @@ please ask administrator to execute the following commands: > sudo gitlab-rails console # Login to Rails console of GitLab instance. > Feature.enabled?(:merge_trains_enabled) # Check if it's enabled or not. > Feature.disable(:merge_trains_enabled) # Disable the feature flag. -```
\ No newline at end of file +``` diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index cb8d383f7d9..61f260cb70d 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -205,5 +205,5 @@ Some features are not implemented yet. For example, support for environments. - `stage` - `allow_failure` - `only` and `except` -- `when` +- `when` (only with `on_success`, `on_failure`, and `always` values) - `extends` diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index ed8d0e3bc35..eaa6efc526d 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -377,6 +377,10 @@ This functionality is only available: - For users with at least Developer access. - If the the stage contains [manual actions](#manual-actions-from-pipeline-graphs). +## Most Recent Pipeline + +There's a link to the latest pipeline for the last commit of a given branch at `/project/pipelines/[branch]/latest`. Also, `/project/pipelines/latest` will redirect you to the latest pipeline for the last commit on the project's default branch. + ## Security on protected branches A strict security model is enforced when pipelines are executed on diff --git a/doc/ci/quick_start/img/build_log.png b/doc/ci/quick_start/img/build_log.png Binary files differindex 2bf0992c50e..16698629edc 100644 --- a/doc/ci/quick_start/img/build_log.png +++ b/doc/ci/quick_start/img/build_log.png diff --git a/doc/ci/quick_start/img/builds_status.png b/doc/ci/quick_start/img/builds_status.png Binary files differindex 58978e23978..b4aeeb988d2 100644 --- a/doc/ci/quick_start/img/builds_status.png +++ b/doc/ci/quick_start/img/builds_status.png diff --git a/doc/ci/quick_start/img/pipelines_status.png b/doc/ci/quick_start/img/pipelines_status.png Binary files differindex 06d1559f5d2..39a77a26b25 100644 --- a/doc/ci/quick_start/img/pipelines_status.png +++ b/doc/ci/quick_start/img/pipelines_status.png diff --git a/doc/ci/quick_start/img/runners_activated.png b/doc/ci/quick_start/img/runners_activated.png Binary files differindex cd83c1a7e4c..ac09e1d0137 100644 --- a/doc/ci/quick_start/img/runners_activated.png +++ b/doc/ci/quick_start/img/runners_activated.png diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 8474d4ef66e..abb503c6516 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -88,7 +88,7 @@ visit the project you want to make the Runner work for in GitLab: ## Registering a group Runner -Creating a group Runner requires Maintainer permissions for the group. To create a +Creating a group Runner requires Owner permissions for the group. To create a group Runner visit the group you want to make the Runner work for in GitLab: 1. Go to **Settings > CI/CD** to obtain the token @@ -124,9 +124,9 @@ To lock/unlock a Runner: ## Assigning a Runner to another project -If you are Maintainer on a project where a specific Runner is assigned to, and the +If you are an Owner on a project where a specific Runner is assigned to, and the Runner is not [locked only to that project](#locking-a-specific-runner-from-being-enabled-for-other-projects), -you can enable the Runner also on any other project where you have Maintainer permissions. +you can enable the Runner also on any other project where you have Owner permissions. To enable/disable a Runner in your project: @@ -156,8 +156,7 @@ An admin can enable/disable a specific Runner for projects: ## Protected Runners -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) -> in GitLab 10.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) in GitLab 10.0. You can protect Runners from revealing sensitive information. Whenever a Runner is protected, the Runner picks only jobs created on @@ -250,7 +249,7 @@ When you [register a Runner][register], its default behavior is to **only pick** [tagged jobs](../yaml/README.md#tags). NOTE: **Note:** -Maintainer [permissions](../../user/permissions.md) are required to change the +Owner [permissions](../../user/permissions.md) are required to change the Runner settings. To make a Runner pick untagged jobs: diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index 9ea113969c8..ce69a7df885 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -27,8 +27,8 @@ variables: NOTE: **Note:** The `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables can't be set in the GitLab UI. -To set them, assign them to a variable [in the UI](../variables/README.md#via-the-ui), -and then assign that variable to the +To set them, assign them to a variable [in the UI](../variables/README.md#via-the-ui), +and then assign that variable to the `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables in your `.gitlab-ci.yml`. And then configure your application to use the database, for example: diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index d9f022a7125..b6aebd3bd78 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -76,7 +76,7 @@ to access it. This is where an SSH key pair comes in handy. ## without extra base64 encoding. ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556 ## - - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null + - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - ## ## Create the SSH directory and give it the right permissions diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 2a382f18038..f62a4660713 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -58,8 +58,7 @@ Read more about the [pipelines trigger API][trigapi]. #### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)** -> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346] - in [GitLab Premium][ee] 9.5. +> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346] in [GitLab Premium][ee] 9.5. With the introduction of dependencies between different projects, one of them may need to access artifacts created by a previous one. This process @@ -271,7 +270,7 @@ Old triggers, created before GitLab 9.0 will be marked as legacy. Triggers with the legacy label do not have an associated user and only have access to the current project. They are considered deprecated and will be -removed with one of the future versions of GitLab. +removed with one of the future versions of GitLab. [ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017 [ee-2346]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2346 diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index d741482b662..5a15b907da0 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -94,7 +94,10 @@ This means that the value of the variable will be hidden in job logs, though it must match certain requirements to do so: - The value must be in a single line. -- The value must only consist of characters from the Base64 alphabet ([RFC4648](https://tools.ietf.org/html/rfc4648)) with the addition of `@` and `:`. +- The value must only consist of characters from the Base64 alphabet (RFC4648). + + [In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-ce/issues/63043) + and newer, `@` and `:` are also valid values. - The value must be at least 8 characters long. - The value must not use variables. @@ -509,7 +512,7 @@ Below you can find supported syntax reference: 1. Checking for an empty variable Examples: - + - `$VARIABLE == ""` - `$VARIABLE != ""` (introduced in GitLab 11.11) diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 2be93433b36..38276de6791 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -100,6 +100,7 @@ The following table lists available parameters for jobs: | [`stage`](#stage) | Defines a job stage (default: `test`). | | [`only`](#onlyexcept-basic) | Limit when jobs are created. Also available: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced). | | [`except`](#onlyexcept-basic) | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced). | +| [`rules`](#rules) | List of coniditions to evaluate and determine selected attributes of a build and whether or not it is created. May not be used alongside `only`/`except`. | [`tags`](#tags) | List of tags which are used to select Runner. | | [`allow_failure`](#allow_failure) | Allow job to fail. Failed job doesn't contribute to commit status. | | [`when`](#when) | When to run job. Also available: `when:manual` and `when:delayed`. | @@ -386,7 +387,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)). | -| `chats` | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. | +| `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-`, whereas all branches will be skipped: @@ -518,10 +519,24 @@ Four keys are available: - `changes` - `kubernetes` -If you use multiple keys under `only` or `except`, they act as an AND. The logic is: +If you use multiple keys under `only` or `except`, the keys will be evaluated as a +single conjoined expression. That is: + +- `only:` means "include this job if all of the conditions match". +- `except:` means "exclude this job if any of the conditions match". + +With `only`, individual keys are logically joined by an AND: > (any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active) +`except` is implemented as a negation of this complete expression: + +> NOT((any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active)) + +This, more intuitively, means the keys join by an OR. A functionally equivalent expression: + +> (any of refs) OR (any of variables) OR (any of changes) OR (if kubernetes is active) + #### `only:refs`/`except:refs` > `refs` policy introduced in GitLab 10.0. @@ -676,6 +691,125 @@ In the scenario above, if a merge request is created or updated that changes either files in `service-one` directory or the `Dockerfile`, GitLab creates and triggers the `docker build service one` job. +### `rules` + +Using `rules` allows for a list of individual rule objects to be evaluated +*in order*, until one matches and dynamically provides attributes to the job. + +Available rule clauses include: + +- `if` (similar to [`only:variables`](#onlyvariablesexceptvariables)). +- `changes` (same as [`only:changes`](#onlychangesexceptchanges)). + +For example, using `if`: + +```yaml +job: + script: "echo Hello, Rules!" + rules: + - if: '$CI_MERGE_REQUEST_TARGET_BRANCH == "master"' # This rule will be evaluated + when: always + - if: '$VAR =~ /pattern/' # This rule will only be evaluated if the first does not match + when: manual + - when: on_success # A Rule entry with no conditional clauses evaluates to true. If neither of the first two Rules match, this one will and set job:when to "on_success" +``` + +If the first rule does not match, further rules will be evaluated sequentially +until a match is found. The above configuration will specify that `job` should +be built and run for every pipeline on merge requests targeting `master`, +regardless of the status of other builds. + +#### `rules:if` + +`rules:if` differs slightly from `only:variables` by accepting only a single +expression string, rather than an array of them. Any set of expressions to be +evaluated should be conjoined into a single expression using `&&` or `||`. For example: + +```yaml +job: + script: "echo Hello, Rules!" + rules: + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH == "master"' # This rule will be evaluated + when: always + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH =~ /^feature/' # This rule will only be evaluated if the target branch is not "master" + when: manual + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH' # If neither of the first two match but the simple presence does, we set to "on_success" by default +``` + +If none of the provided rules match, the job will be set to `when:never`, and +not included in the pipeline. If `rules:when` is not included in the configuration +at all, the behavior defaults to `job:when`, which continues to default to +`on_success`. + +#### `rules:changes` + +`changes` works exactly the same way as [`only`/`except`](#onlychangesexceptchanges), +accepting an array of paths. The following configuration configures a job to be +run manually if `Dockerfile` has changed OR `$VAR == "string value"`. Otherwise +it is set to `when:on_success` by the last rule, where 0 clauses evaluate as +vacuously true. + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. + - Dockerfile + when: manual + - if: '$VAR == "string value"' + when: manual # Will include the job and set to when:manual if the expression evaluates to true, after the `changes:` rule fails to match. + - when: on_success # If neither of the first rules match, set to on_success + +``` + +#### Complex Rule Clauses + +To conjoin `if` and `changes` clauses with an AND, use them in the same rule. +Here we run the job manually if `Dockerfile` or any file in `docker/scripts/` +has changed AND `$VAR == "string value"`. Otherwise, the job will not be +included in the pipeline. + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - if: '$VAR == "string value"' + changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. + - Dockerfile + - docker/scripts/* + when: manual + # - when: never would be redundant here, this is implied any time rules are listed. +``` + +The only clauses currently available are `if` and `changes`. Keywords such as +`branches` or `refs` that are currently available for `only`/`except` are not +yet available in `rules` as they are being individually considered for their +usage and behavior in the newer context. + +#### Permitted attributes + +The only job attributes currently set by `rules` are `when` and `start_in`, if +`when` is set to `delayed`. A job will be included in a pipeline if `when` is +evaluated to any value except `never`. + +Delayed jobs require a `start_in` value, so rule objects do as well. For example: + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - changes: # Will include the job and delay 3 hours when the Dockerfile has changed + - Dockerfile + when: delayed + start_in: '3 hours' + - when: on_success # Otherwise include the job and set to run normally + +``` + +Additional Job configuration may be added to rules in the future, if something +useful isn't available, please open an issue on +[Gitlab CE](https://www.gitlab.com/gitlab-org/gitlab-ce/issues). + ### `tags` `tags` is used to select specific Runners from the list of all Runners that are @@ -1565,10 +1699,10 @@ dashboards. > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. -The `license_management` report collects [Licenses](../../user/project/merge_requests/license_management.md) +The `license_management` report collects [Licenses](../../user/application_security/license_compliance/index.md) as artifacts. -The collected License Management report will be uploaded to GitLab as an artifact and will +The collected License Compliance report will be uploaded to GitLab as an artifact and will be automatically shown in merge requests, pipeline view and provide data for security dashboards. @@ -1686,19 +1820,19 @@ mac:build: linux:rspec: stage: test - needs: [linux:build] + needs: ["linux:build"] linux:rubocop: stage: test - needs: [linux:build] + needs: ["linux:build"] mac:rspec: stage: test - needs: [mac:build] + needs: ["mac:build"] mac:rubocop: stage: test - needs: [mac:build] + needs: ["mac:build"] production: stage: deploy @@ -1721,7 +1855,7 @@ This example creates three paths of execution: 1. If `needs:` is set to point to a job that is not instantiated because of `only/except` rules or otherwise does not exist, the job will fail. -1. Note that one day one of the launch, we are temporarily limiting the +1. Note that on day one of the launch, we are temporarily limiting the maximum number of jobs that a single job can need in the `needs:` array. Track our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/7541) for details on the current limit. @@ -1734,8 +1868,8 @@ This example creates three paths of execution: in the first stage (see [gitlab-ce#65504](https://gitlab.com/gitlab-org/gitlab-ce/issues/65504)). 1. If `needs:` refers to a job that is marked as `parallel:`. the current job will depend on all parallel jobs created. -1. `needs:` is similar to `dependencies:` in that needs to use jobs from - prior stages, this means that it is impossible to create circular +1. `needs:` is similar to `dependencies:` in that it needs to use jobs from + prior stages, meaning it is impossible to create circular dependencies or depend on jobs in the current stage (see [gitlab-ce#65505](https://gitlab.com/gitlab-org/gitlab-ce/issues/65505)). 1. Related to the above, stages must be explicitly defined for all jobs that have the keyword `needs:` or are referred to by one. @@ -1765,9 +1899,8 @@ job1: ### `retry` -> [Introduced][ce-12909] in GitLab 9.5. -> [Behaviour expanded](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21758) -> in GitLab 11.5 to control on which failures to retry. +> - [Introduced][ce-12909] in GitLab 9.5. +> - [Behaviour expanded](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21758) in GitLab 11.5 to control on which failures to retry. `retry` allows you to configure how many times a job is going to be retried in case of a failure. @@ -1856,6 +1989,7 @@ Marking a job to be run in parallel requires only a simple addition to your conf script: rspec + parallel: 5 ``` + TIP: **Tip:** Parallelize tests suites across parallel jobs. Different languages have different tools to facilitate this. |
