GitLab CI/CD Pipeline Configuration Reference：一 [Global inherit stages workflow rules include]

GitLab CI/CD pipelines are configured using a YAML file called .gitlab-ci.yml within each project.

The .gitlab-ci.yml file defines the structure and order of the pipelines and determines:

• What to execute using GitLab Runner.
• What decisions to make when specific conditions are encountered. For example, when a process succeeds or fails.

This topic covers CI/CD pipeline configuration. For other CI/CD configuration information, see:

• GitLab CI/CD Variables, for configuring the environment the pipelines run in.
• GitLab Runner advanced configuration, for configuring GitLab Runner.

We have complete examples of configuring pipelines:

• For a quick introduction to GitLab CI/CD, follow our quick start guide.
• For a collection of examples, see GitLab CI/CD Examples.
• To see a large .gitlab-ci.yml file used in an enterprise, see the .gitlab-ci.yml file for gitlab.

NOTE: Note: If you have a mirrored repository where GitLab pulls from, you may need to enable pipeline triggering in your project's Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates.

Introduction

Pipeline configuration begins with jobs. Jobs are the most fundamental element of a .gitlab-ci.yml file.

Jobs are:

• Defined with constraints stating under what conditions they should be executed.
• Top-level elements with an arbitrary name and must contain at least the script clause.
• Not limited in how many can be defined.

For example:

job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"

The above example is the simplest possible CI/CD configuration with two separate jobs, where each of the jobs executes a different command. Of course a command can execute code directly (./configure;make;make install) or run a script (test.sh) in the repository.

Jobs are picked up by Runners and executed within the environment of the Runner. What is important, is that each job is run independently from each other.

Validate the .gitlab-ci.yml

Each instance of GitLab CI/CD has an embedded debug tool called Lint, which validates the content of your .gitlab-ci.yml files. You can find the Lint under the page ci/lint of your project namespace. For example, https://gitlab.example.com/gitlab-org/project-123/-/ci/lint.

Unavailable names for jobs

Each job must have a unique name, but there are a few reserved keywords that can't be used as job names:

• image
• services
• stages
• types
• before_script
• after_script
• variables
• cache
• include

Using reserved keywords

If you get validation error when using specific values (for example, true or false), try to:

• Quote them.
• Change them to a different form. For example, /bin/true.

Configuration parameters

A job is defined as a list of parameters that define the job's behavior.

The following table lists available parameters for jobs:

Keyword	Description
script	Shell script which is executed by Runner.
image	Use docker images. Also available: image:name and image:entrypoint.
services	Use docker services images. Also available: services:name, services:alias, services:entrypoint, and services:command.
before_script	Override a set of commands that are executed before job.
after_script	Override a set of commands that are executed after job.
stage	Defines a job stage (default: test).
only	Limit when jobs are created. Also available: only:refs, only:kubernetes, only:variables, and only:changes.
except	Limit when jobs are not created. Also available: except:refs, except:kubernetes, except:variables, and except:changes.
rules	List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. May not be used alongside only/except.
tags	List of tags which are used to select Runner.
allow_failure	Allow job to fail. Failed job does not contribute to commit status.
when	When to run job. Also available: when:manual and when:delayed.
environment	Name of an environment to which the job deploys. Also available: environment:name, environment:url, environment:on_stop, environment:auto_stop_in and environment:action.
cache	List of files that should be cached between subsequent runs. Also available: cache:paths, cache:key, cache:untracked, and cache:policy.
artifacts	List of files and directories to attach to a job on success. Also available: artifacts:paths, artifacts:expose_as, artifacts:name, artifacts:untracked, artifacts:when, artifacts:expire_in, artifacts:reports, artifacts:reports:junit, artifacts:reports:cobertura, and artifacts:reports:terraform. In GitLab Enterprise Edition, these are available: artifacts:reports:codequality, artifacts:reports:sast, artifacts:reports:dependency_scanning, artifacts:reports:container_scanning, artifacts:reports:dast, artifacts:reports:license_scanning, artifacts:reports:license_management (removed in GitLab 13.0),artifacts:reports:performance and artifacts:reports:metrics.
dependencies	Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from.
coverage	Code coverage settings for a given job.
retry	When and how many times a job can be auto-retried in case of a failure.
timeout	Define a custom job-level timeout that takes precedence over the project-wide setting.
parallel	How many instances of a job should be run in parallel.
trigger	Defines a downstream pipeline trigger.
include	Allows this job to include external YAML files. Also available: include:local, include:file, include:template, and include:remote.
extends	Configuration entries that this job is going to inherit from.
pages	Upload the result of a job to use with GitLab Pages.
variables	Define job variables on a job level.
interruptible	Defines if a job can be canceled when made redundant by a newer run.
resource_group	Limit job concurrency.

NOTE: Note: Parameters types and type are deprecated.

Global parameters

Some parameters must be defined at a global level, affecting all jobs in the pipeline.

Global defaults

Some parameters can be set globally as the default for all jobs using the default: keyword. Default parameters can then be overridden by job-specific configuration. （default区域的值可以被Job区域覆盖）

The following job parameters can be defined inside a default: block:

• image
• services
• before_script
• after_script
• tags
• cache
• artifacts
• retry
• timeout
• interruptible

In the following example, the ruby:2.5 image is set as the default for all jobs except the rspec 2.6 job, which uses the ruby:2.6 image:

default:
  image: ruby:2.5

rspec:
  script: bundle exec rspec

rspec 2.6:
  image: ruby:2.6
  script: bundle exec rspec

inherit

Introduced in GitLab 12.9.

You can disable inheritance of globally defined defaults and variables with the inherit: parameter.

To enable or disable the inheritance of all variables: or default: parameters, use the following format:

• default: true or default: false
• variables: true or variables: false

To inherit only a subset of default: parameters or variables:, specify what you wish to inherit, and any not listed will not be inherited. Use one of the following formats:

inherit:
  default: [parameter1, parameter2]
  variables: [VARIABLE1, VARIABLE2]

Or:

inherit:
  default:
    - parameter1
    - parameter2
  variables:
    - VARIABLE1
    - VARIABLE2

In the example below: (下面示例很好的说明了 Global变量在 Job中继承的关系)

• rubocop:
  • will inherit: Nothing.
• rspec:
  • will inherit: the default image and the WEBHOOK_URL variable.
  • will not inherit: the default before_script and the DOMAIN variable.
• capybara:
  • will inherit: the default before_script and image.
  • will not inherit: the DOMAIN and WEBHOOK_URL variables.
• karma:
  • will inherit: the default image and before_script, and the DOMAIN variable.
  • will not inherit: WEBHOOK_URL variable.

default:
  image: 'ruby:2.4'
  before_script:
    - echo Hello World

variables:
  DOMAIN: example.com
  WEBHOOK_URL: https://my-webhook.example.com

rubocop:
  inherit:
    default: false
    variables: false
  script: bundle exec rubocop

rspec:
  inherit:
    default: [image]
    variables: [WEBHOOK_URL]
  script: bundle exec rspec

capybara:
  inherit:
    variables: false
  script: bundle exec capybara

karma:
  inherit:
    default: true
    variables: [DOMAIN]
  script: karma

stages

stages is used to define stages that can be used by jobs and is defined globally.

（stages 被定义在全局区域，用来定义不同的stage被jobs使用 ）

The specification of stages allows for having flexible multi stage pipelines. The ordering of elements in stages defines the ordering of jobs' execution: (stages中元素的定义顺序决定了jobs的执行顺序)

1. Jobs of the same stage are run in parallel.   （拥有相同stage的Job并行执行）
2. Jobs of the next stage are run after the jobs from the previous stage complete successfully.  （处于下一个阶段的stage需要在前一个stage成功完成以后执行）

Let's consider the following example, which defines 3 stages:

stages:
  - build
  - test
  - deploy

1. First, all jobs of build are executed in parallel.    都是处于 stage: build 的 jobs开始并行执行
2. If all jobs of build succeed, the test jobs are executed in parallel.  当处于 stage: build 的 jobs全部执行成功，stage: test 开始并行执行
3. If all jobs of test succeed, the deploy jobs are executed in parallel. 当处于 stage: test 的 jobs全部执行成功，stage: deploy 开始并行执行
4. If all jobs of deploy succeed, the commit is marked as passed.  当处于 stage: deploy 的 jobs全部执行成功，本次commit被标记为passed
5. If any of the previous jobs fails, the commit is marked as failed and no jobs of further stage are executed.   当上述过程有任何一个job运行失败，commit被标记为failed并且剩下的jobs不会执行

There are also two edge cases worth mentioning:  （需要特别注意的两点）

1. If no stages are defined in .gitlab-ci.yml, then the build, test and deploy are allowed to be used as job's stage by default.  如果.gitlab-ci.yml中没有定义stages，build, test and deploy依然可以被job使用

2. If a job does not specify a stage, the job is assigned the test stage.  如果一个Job没有设定具体的stage，那么该Job被默认归属于stage: test

workflow:rules

Introduced in GitLab 12.5

The top-level workflow: key applies to the entirety of a pipeline, and will determine whether or not a pipeline is created. It currently accepts a single rules: key that operates similarly to rules: defined within jobs, enabling dynamic configuration of the pipeline.

workflow:rules templates

Introduced 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 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 like Pipelines for Merge Results or Merge Trains. Use this template if you are intentionally avoiding those features.

It is included as follows:

include:
  - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'

The MergeRequest-Pipelines include sets your pipelines to run for the default branch (usually master), tags, and The MergeRequest-Pipelines template 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, as mentioned above.

It is included as follows:

include:
  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'

If you prefer to define your own rules, the configuration options currently available are:​  自定义pipeline规则

• if: Define a rule.
• when: May be set to always or never only. If not provided, the default value is always​.

The list of if rules is evaluated until a single one is matched. If none match, the last when will be used:

rules规则列表中，先做if匹配入口判断，如果一个都没有匹配上，则最后一个when的规则会被使用（类似于finally）

workflow:
  rules:
    - if: $CI_COMMIT_REF_NAME =~ /-wip$/
      when: never
    - if: $CI_COMMIT_TAG
      when: never
    - when: always

include：可以将配置与参数进行分离解耦，增加可读性和易维护性

• Introduced in GitLab Premium 10.5.
• Available for Starter, Premium and Ultimate since 10.6.
• Moved to GitLab Core in 11.4.

Using the include keyword allows the inclusion of external YAML files. This helps to break down the CI/CD configuration into multiple files and increases readability for long configuration files（将很长的配置文件切分成较小的配置文件，增加配置的可读性）. It's also possible to have template files stored in a central repository and projects include their configuration files（也可能中央仓库或者项目中存储了模板文件，用来提供配置参数）. This helps avoid duplicated configuration, for example, global default variables for all projects（这样可以帮助我们避免重复的配置，比如配置全局默认的变量）.

include requires the external YAML file to have the extensions .yml or .yaml, otherwise the external file won't be included.  （被引用的外部YAML文件必须是.yml或者.yaml格式的文件，否则不会成功引用）

include supports the following inclusion methods:

Method	Description
local	Include a file from the local project repository.
file	Include a file from a different project repository.
remote	Include a file from a remote URL. Must be publicly accessible.
template	Include templates which are provided by GitLab.

NOTE: Note: .gitlab-ci.yml configuration included by all methods is evaluated at pipeline creation. The configuration is a snapshot in time and persisted in the database. Any changes to referenced .gitlab-ci.yml configuration won't be reflected in GitLab until the next pipeline is created. （当一个pipeline流程使用了一个.gitlab-ci.yml文件中的配置，那么这些配置参数就被固化到了数据库当中，.gitlab-ci.yml的在线更改不会实时反映到正在执行的pipeline，除非修改后，启动下一个pipeline流程）

The files defined in include are:

• Deep merged with those in .gitlab-ci.yml.
• Always evaluated first and merged with the content of .gitlab-ci.yml, regardless of the position of the include keyword.

TIP: Tip: Use merging to customize and override included CI/CD configurations with local definitions.

NOTE: Note: Using YAML aliases across different YAML files sourced by include is not supported. You must only refer to aliases in the same file. Instead of using YAML anchors, you can use the extends keyword.

include:local

include:local includes a file from the same repository as .gitlab-ci.yml. It's referenced using full paths relative to the root directory (/).

include:local 这种包含外部YAML文件的方式，外部YAML文件和 .gitlab-ci.yml处于同一个repository，引用时，需要指定被引用YAML文件相对于/的全路径. 

You can only use files that are currently tracked by Git on the same branch your configuration file is on. In other words, when using a include:local, make sure that both .gitlab-ci.yml and the local file are on the same branch.  需要确保当使用  include:local时，.gitlab-ci.yml and the local file 处于相同的分支

All nested includes will be executed in the scope of the same project, so it's possible to use local, project, remote, or template includes. 嵌套的includes配置在同一个project范围内将被执行

NOTE: Note: Including local files through Git submodules paths is not supported.  通过 Git 子模块来包含 local files是不支持的

Example:

include:
  - local: '/templates/.gitlab-ci-template.yml'

TIP: Tip: Local includes can be used as a replacement for symbolic links which are not followed.

This can be defined as a short local include:

include: '.gitlab-ci-production.yml'

include:file

Introduced in GitLab 11.7.

To include files from another private project under the same GitLab instance, use include:file. This file is referenced using full paths relative to the root directory (/). For example:

include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'

You can also specify ref, with the default being the HEAD of the project:

include:
  - project: 'my-group/my-project'
    ref: master
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: v1.0.0
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA
    file: '/templates/.gitlab-ci-template.yml'

All nested includes will be executed in the scope of the target project, so it's possible to use local (relative to target project), project, remote or template includes.

include:remote

include:remote can be used to include a file from a different location, using HTTP/HTTPS, referenced by using the full URL. The remote file must be publicly accessible through a simple GET request as authentication schemas in the remote URL are not supported. For example:

include:
  - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'

All nested includes will be executed without context as public user, so only another remote or public project, or template, is allowed.

include:template

Introduced in GitLab 11.7.

include:template can be used to include .gitlab-ci.yml templates that are shipped with GitLab.

For example:

# File sourced from GitLab's template collection
include:
  - template: Auto-DevOps.gitlab-ci.yml

Multiple include:template files:

include:

  - template: Android-Fastlane.gitlab-ci.yml
  - template: Auto-DevOps.gitlab-ci.yml

All nested includes will be executed only with the permission of the user, so it's possible to use project, remote or template includes.

模板示例：Python.gitlab-ci.yml 

# Official language image. Look for the different tagged releases at:
# https://hub.docker.com/r/library/python/tags/
image: python:latest

# Change pip's cache directory to be inside the project directory since we can
# only cache local items.
variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

# Pip's cache doesn't store the python packages
# https://pip.pypa.io/en/stable/reference/pip_install/#caching
#
# If you want to also cache the installed packages, you have to install
# them in a virtualenv and cache it as well.
cache:
  paths:
    - .cache/pip
    - venv/

before_script:
  - python -V  # Print out python version for debugging
  - pip install virtualenv
  - virtualenv venv
  - source venv/bin/activate

test:
  script:
    - python setup.py test
    - pip install tox flake8  # you can also use tox
    - tox -e py36,flake8

run:
  script:
    - python setup.py bdist_wheel
    # an alternative approach is to install and run:
    - pip install dist/*
    # run the command here
  artifacts:
    paths:
      - dist/*.whl

pages:
  script:
    - pip install sphinx sphinx-rtd-theme
    - cd doc ; make html
    - mv build/html/ ../public/
  artifacts:
    paths:
      - public
  only:
    - master

Nested includes

Introduced in GitLab 11.9.

Nested includes allow you to compose a set of includes.

A total of 100 includes is allowed, but duplicate includes are considered a configuration error.

Since GitLab 12.4, the time limit for resolving all files is 30 seconds.

Additional includes examples

There is a list of additional includes examples available.  include的用法可以参考：http://10.197.236.131:9800/help/ci/yaml/includes.md 路径信息

---

参考链接：http://10.197.236.131:9800/help/ci/yaml/README.md