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的执行顺序)

Jobs of the same stage are run in parallel. （拥有相同stage的Job并行执行）
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

First, all jobs of build are executed in parallel. 都是处于 stage: build 的 jobs开始并行执行
If all jobs of build succeed, the test jobs are executed in parallel. 当处于 stage: build 的 jobs全部执行成功，stage: test 开始并行执行
If all jobs of test succeed, the deploy jobs are executed in parallel. 当处于 stage: test 的 jobs全部执行成功，stage: deploy 开始并行执行
If all jobs of deploy succeed, the commit is marked as passed. 当处于 stage: deploy 的 jobs全部执行成功，本次commit被标记为passed
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: （需要特别注意的两点）

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使用
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

posted on 2020-06-23 15:04 骑着蜗牛追火车阅读(926) 评论(0) 编辑收藏举报

刷新页面返回顶部

导航

Introduction

Validate the `.gitlab-ci.yml`

Unavailable names for jobs

Using reserved keywords

Configuration parameters

Global parameters

Global defaults

`inherit`

`stages`

`workflow:rules`

`workflow:rules` templates

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

`include:local`

`include:file`

`include:remote`

`include:template`

Nested includes

Additional `includes` examples

导航

Introduction

Validate the .gitlab-ci.yml

Unavailable names for jobs

Using reserved keywords

Configuration parameters

Global parameters

Global defaults

inherit

stages

workflow:rules

workflow:rules templates

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

include:local

include:file

include:remote

include:template

Nested includes

Additional includes examples

Validate the `.gitlab-ci.yml`

`inherit`

`stages`

`workflow:rules`

`workflow:rules` templates

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

`include:local`

`include:file`

`include:remote`

`include:template`

Additional `includes` examples