GitLab CI/CD 备忘清单

本备忘单总结了 GitLab CI/CD 常用的配置说明，以供快速参考

入门

介绍

创建并运行您的第一个 GitLab CI/CD 管道，在开始之前，请确保您拥有：

GitLab 中您想要使用 CI/CD 的项目
项目的维护者或所有者角色

如果您没有项目，可以在 https://gitlab.com 上免费创建一个公共项目

在存储库的根目录下创建一个 .gitlab-ci.yml 文件。该文件是您定义 CI/CD 作业的地方
转到Settings > CI/CD 并展开运行程序，只要您至少有一个运行器处于活动状态，旁边有一个绿色圆圈，您就有一个运行器可以处理您的工作

示例

default:
  image: node:16

windows_job:
  only:
    - master
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

linux_job:
  tags:
    - linux
  script:
    - echo "Hello, $USER!"

tags 用于在不同的平台上运行作业，only 控制 master 分支提交触发

关键字

关键字	描述
default	工作关键字的自定义默认值 #
include	从其他 YAML 文件导入配置 #
stages	管道阶段的名称和顺序 #
variables	为管道中的所有作业定义 CI/CD 变量 #
workflow	控制运行什么类型的管道 #

关键字

关键字	描述
after_script	覆盖一组在作业之后执行的命令 #
allow_failure	允许作业失败。失败的作业不会导致管道失败 #
artifacts	成功时附加到作业的文件和目录列表 #
before_script	覆盖在作业之前执行的一组命令 #
cache	应在后续运行之间缓存的文件列表 #
coverage	给定作业的代码覆盖率设置 #
dast_configuration	在作业级别使用 DAST 配置文件中的配置 #
dependencies	通过提供要从中获取工件的作业列表来限制将哪些工件传递给特定作业 #
environment	作业部署到的环境的名称 #
except	控制何时不创建作业 #
extends	此作业继承自的配置条目 #
image	使用 Docker 镜像 #
inherit	选择所有作业继承的全局默认值 #
interruptible	定义作业是否可以在被较新的运行冗余时取消 #
needs	在阶段排序之前执行作业 #
only	控制何时创建作业 #
pages	上传作业的结果以与 GitLab Pages 一起使用 #
parallel	应并行运行多少个作业实例 #
release	指示运行器生成释放对象 #
resource_group	限制作业并发 #
retry	发生故障时可以自动重试作业的时间和次数 #
rules	用于评估和确定作业的选定属性以及是否创建的条件列表 #
script	由运行器执行的 Shell 脚本 #
secrets	CI/CD 保密工作需要 #
services	使用 Docker 服务映像 #
stage	定义作业阶段 #
tags	用于选择跑步者的标签列表 #
timeout	定义优先于项目范围设置的自定义作业级超时 #
trigger	定义下游管道触发器 #
variables	在作业级别定义作业变量 #
when	何时运行作业 #

全局关键词

default

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: ruby:2.7
  script: bundle exec rspec

在此示例中，ruby:3.0 是管道中所有作业的默认图像值。rspec 2.7 作业不使用默认值，因为它使用特定于作业的图像部分覆盖了默认值

include

1 2	include: - local: '/temp/.gitlab-ci-template.yml'

在 11.4 中移至 GitLab 免费版，使用 include 将外部 YAML 文件包含在您的 CI/CD 配置中

include:local

1 2	include: - local: '/temp/.gitlab-ci-template.yml'

使用 include:local 包含与 .gitlab-ci.yml 文件位于同一存储库中的文件

include:project

要在同一个 GitLab 实例上包含来自另一个私有项目的文件，请使用 include:project 和 include:file

include:
  - project: 'group/my-project'
    file: '/temp/.gitlab-ci-template.yml'
  - project: 'group/subgroup/my-project-2'
    file:
      - '/temp/.builds.yml'
      - '/temp/.tests.yml'

您还可以指定一个 ref：

include:
  - project: 'group/my-project'
    ref: main    # Git branch
    file: '/templates/.gitlab-ci.yml'
  - project: 'group/my-project'
    ref: v1.0.0   # Git Tag
    file: '/templates/.gitlab-ci.yml'
  - project: 'group/my-project'
    ref: 787123b  # Git SHA
    file: '/templates/.gitlab-ci.yml'

include:remote

1 2	include: - remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'

使用带有完整 URL 的 include:remote 来包含来自不同位置的文件

include:template

使用 include:template 来包含 .gitlab-ci.yml 模板

1
2
3

# 文件来自 GitLab 模板集合
include:
  - template: Auto-DevOps.gitlab-ci.yml

多个 include:template 文件：

1
2
3

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

stages

使用阶段来定义包含作业组的阶段。如果 .gitlab-ci.yml 文件中未定义阶段，则默认管道阶段为：

.pre
build
test
deploy
.post

stages:
  - build
  - test
  - deploy

workflow

workflow:name

您可以在 workflow: 中使用 name 来定义管道的名称

1 2	workflow: name: '分支管道：$CI_COMMIT_BRANCH'

根据管道条件具有不同管道名称的配置：

variables:
  PIPELINE_NAME: '默认管道名称'

workflow:
  name: '$PIPELINE_NAME'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PIPELINE_NAME: 'MR pipeline: $CI_COMMIT_BRANCH'
    - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/'
      variables:
        PIPELINE_NAME: 'Ruby 3 pipeline'

workflow:rules:variables

您可以在 workflow:rules 中使用变量来定义特定管道条件的变量

variables:
  DEPLOY_VARIABLE: "default-deploy"

workflow:
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:
        DEPLOY_VARIABLE: "deploy-production"  # 覆盖全局定义的 DEPLOY_VARIABLE
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # 定义一个新变量
    - when: always                            # 在其他情况下运行管道

job1:
  variables:
    DEPLOY_VARIABLE: "job1-default-deploy"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:                                   # 覆盖定义的 DEPLOY_VARIABLE
        DEPLOY_VARIABLE: "job1-deploy-production"  # 在工作层面。
    - when: on_success                             # 在其他情况下运行作业
  script:
    - echo "以 $DEPLOY_VARIABLE 作为参数运行脚本"
    - echo "如果 $IS_A_FEATURE 存在则运行另一个脚本"

job2:
  script:
    - echo "以 $DEPLOY_VARIABLE 作为参数运行脚本"
    - echo "如果 $IS_A_FEATURE 存在则运行另一个脚本"

workflow:rules

工作流(workflow)中的 rules 关键字类似于作业中定义的 rules，但控制是否创建整个管道

rules: if
rules: changes
rules: exists
when
variables

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Job 关键词

after_script

在每个作业（包括失败的作业）之后运行的命令数组

job:
  script:
    - echo "示例脚本部分"
  after_script:
    - echo "在“script”部分完成后执行此命令"

allow_failure

确定管道是否应在作业失败时继续运行

job1:
  stage: test
  script:
    - execute_script_1

job2:
  stage: test
  script:
    - execute_script_2
  allow_failure: true

job3:
  stage: deploy
  script:
    - deploy_to_staging
  environment: staging

allow_failure:exit_codes

控制何时允许作业失败。对于任何列出的退出代码，作业是 allow_failure: true，对于任何其他退出代码，allow_failure false

test_job_1:
  script:
    - echo "退出代码 1 的脚本。此作业失败"
    - exit 1
  allow_failure:
    exit_codes: 137

test_job_2:
  script:
    - echo "退出代码 137 的脚本允许此作业失败"
    - exit 137
  allow_failure:
    exit_codes:
      - 137
      - 255

dast_configuration

stages:
  - build
  - dast

include:
  - template: DAST.gitlab-ci.yml

dast:
  dast_configuration:
    site_profile: "Example Co"
    scanner_profile: "Quick Passive Test"

指定要在 CI/CD 配置中使用的站点配置文件和扫描仪配置文件。两个配置文件必须首先在项目中创建。作业的阶段必须快

before_script

在每个作业的 script 命令之前运行，但在工件恢复之后运行

job:
  before_script:
    - echo "在任何“script:”命令之前执行此命令"
  script:
    - echo "“before_script”命令之后执行"

coverage

1
2
3

job1:
  script: rspec
  coverage: '/Code coverage: \d+\.\d+/'

使用自定义正则表达式的覆盖率来配置如何从作业输出中提取代码覆盖率

extends

.tests:
  script: rake test
  stage: test
  only:
    refs:
      - branches

rspec:
  extends: .tests
  script: rake rspec
  only:
    variables:
      - $RSPEC

使用 extends 重用配置部分。它是 YAML 锚点的替代品，并且更加灵活和可读

dependencies

build osx:
  stage: build
  script: make build:osx
  artifacts:
    paths:
      - binaries/

build linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
      - binaries/

test osx:
  stage: test
  script: make test:osx
  dependencies:
    - build osx

test linux:
  stage: test
  script: make test:linux
  dependencies:
    - build linux

deploy:
  stage: deploy
  script: make deploy
  environment: production

定义要从中获取工件的作业列表。您还可以将作业设置为根本不下载任何工件

inherit

使用 inherit 控制默认关键字和变量的继承

inherit:default

使用 inherit:default 控制 default 关键字的继承

default:
  retry: 2
  image: ruby:3.0
  interruptible: true

job1:
  script: echo "此作业不继承任何默认关键字"
  inherit:
    default: false

job2:
  script: echo "此作业仅继承列出的两个默认关键字。它不继承“可中断”"
  inherit:
    default:
      - retry
      - image

inherit:variables

使用 inherit:variables 控制全局变量关键字的继承

variables:
  VARIABLE1: "这是变量 1"
  VARIABLE2: "这是变量 2"
  VARIABLE3: "这是变量 3"

job1:
  script: echo "该作业不继承任何全局变量"
  inherit:
    variables: false

job2:
  script: echo "此作业仅继承列出的两个全局变量。它不继承“VARIABLE3”"
  inherit:
    variables:
      - VARIABLE1
      - VARIABLE2

interruptible

stages:
  - stage1
  - stage2
  - stage3

step-1:
  stage: stage1
  script:
    - echo "可以取消"
  interruptible: true

step-2:
  stage: stage2
  script:
    - echo "不能取消"

step-3:
  stage: stage3
  script:
    - echo "因为第 2 步无法取消，所以此步骤永远无法取消，即使它被设置为可中断"
  interruptible: true

如果在作业完成之前启动较新的管道时应取消作业，则使用可中断的

pages

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

使用页面定义将静态内容上传到 GitLab 的 GitLab Pages 作业。然后将内容发布为网站

parallel

1
2
3

test:
  script: rspec
  parallel: 5

使用 parallel 在单个管道中并行多次运行作业

parallel:matrix

deploystacks:
  stage: deploy
  script:
    - bin/deploy
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2
      - PROVIDER: ovh
        STACK: [monitoring, backup, app]
      - PROVIDER: [gcp, vultr]
        STACK: [data, processing]
  environment: $PROVIDER/$STACK

使用 parallel:matrix 在单个管道中并行多次运行作业，但每个作业实例具有不同的变量值

resource_group

1
2
3

deploy-to-production:
  script: deploy
  resource_group: production

创建一个资源组，以确保作业在同一项目的不同管道之间互斥

retry

1
2
3

test:
  script: rspec
  retry: 2

使用 retry 配置作业失败时重试的次数。如果未定义，则默认为 0，并且作业不会重试

retry:when

test:
  script: rspec
  retry:
    max: 2
    when: runner_system_failure

使用 retry:when 和 retry:max 来重试特定失败案例的作业。 retry:max 是最大重试次数，和retry一样，可以是0、1、2

script

job1:
  script: "bundle exec rspec"

job2:
  script:
    - uname -a
    - bundle exec rspec

使用脚本指定运行器执行的命令

secrets

此关键字必须与 secrets:vault 一起使用

secrets:vault

使用 secrets:vault 指定 HashiCorp Vault 提供的秘密

job:
  secrets:
    # 将秘密的路径存储在此 CI/CD 变量中
    DATABASE_PASSWORD:
      # 转换为秘密：`ops/data/production/db`
      # 字段：`password`
      vault: 
        engine:
          name: kv-v2
          path: ops
        path: production/db
        field: password

secrets:file

使用 secrets:file 将秘密配置为存储为文件或变量类型的 CI/CD 变量

job:
  secrets:
    DATABASE_PASSWORD:
      vault: production/db/password@ops
      file: false

timeout

build:
  script: build.sh
  timeout: 3 hours 30 minutes

test:
  script: rspec
  timeout: 3h 30m

为特定作业配置超时。如果作业运行时间超过超时时间，则作业失败

services

使用服务指定额外的 Docker 映像以在其中运行脚本

default:
  image:
    name: ruby:2.6
    entrypoint: ["/bin/bash"]

  services:
    - name: my-postgres:11.7
      alias: db-postgres
      entrypoint: ["/usr/local/bin/db-postgres"]
      command: ["start"]

  before_script:
    - bundle install

test:
  script:
    - bundle exec rake spec

service:pull_policy

运行器用于获取 Docker 映像的拉取策略

job1:
  script: echo "A single pull policy."
  services:
    - name: postgres:11.6
      pull_policy: if-not-present

job2:
  script: echo "Multiple pull policies."
  services:
    - name: postgres:11.6
      pull_policy: [always, if-not-present]

stage

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - echo "这项工作编译代码"

job2:
  stage: test
  script:
    - echo "此作业测试编译后的代码。它在构建阶段完成时运行"

job3:
  script:
    - echo "这项工作也在测试阶段运行"

job4:
  stage: deploy
  script:
    - echo "此作业部署代码。它在测试阶段完成时运行"
  environment: production

stage: .pre

stages:
  - build
  - test

job1:
  stage: build
  script:
    - echo "该作业在构建阶段运行"

first-job:
  stage: .pre
  script:
    - echo "该作业在 .pre 阶段运行，在所有其他阶段之前"

job2:
  stage: test
  script:
    - echo "该作业在测试阶段运行"

stage: .post

stages:
  - build
  - test

job1:
  stage: build
  script:
    - echo "该作业在构建阶段运行"

last-job:
  stage: .post
  script:
    - echo "该作业在 .post 阶段运行，在所有其他阶段之后"

job2:
  stage: test
  script:
    - echo "该作业在测试阶段运行"

trigger

声明一个作业是一个“触发作业”

1 2	trigger-multi-project-pipeline: trigger: my-group/my-project

trigger:include

1
2
3

trigger-child-pipeline:
  trigger:
    include: path/to/child-pipeline.gitlab-ci.yml

声明作业是启动子管道的“触发器作业”

trigger:project

1
2
3

trigger-multi-project-pipeline:
  trigger:
    project: my-group/my-project

声明作业是启动多项目管道的“触发器作业”

trigger:strategy

trigger-multi-project-pipeline:
  trigger:
    project: my-group/my-project
    branch: development

强制触发作业等待下游管道完成后再标记为成功

trigger:forward

variables: # 每个作业的默认变量
  VAR: value

# 默认行为：
# - VAR 传递给孩子
# - MYVAR 没有传递给孩子
child1:
  trigger:
    include: .child-pipeline.yml

# 转发管道变量：
# - VAR 传递给孩子
# - MYVAR 传递给孩子
child2:
  trigger:
    include: .child-pipeline.yml
    forward:
      pipeline_variables: true

# 不要转发 YAML 变量：
# - VAR 不会传递给孩子
# - MYVAR 没有传递给孩子
child3:
  trigger:
    include: .child-pipeline.yml
    forward:
      yaml_variables: false

variables

CI/CD 变量是传递给作业的可配置值。使用变量创建自定义变量

variables:
  DEPLOY_SITE: "https://example.com/"

deploy_job:
  stage: deploy
  script:
    - deploy-script --url $DEPLOY_SITE --path "/"
  environment: production

deploy_review_job:
  stage: deploy
  variables:
    REVIEW_PATH: "/review"
  script:
    - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH
  environment: production

variables:description

variables:
  DEPLOY_ENVIRONMENT:
    description: "部署目标。 如果需要，将此变量更改为“canary”或“production”"
    value: "staging"

variables:expand

variables:
  VAR1: value1
  VAR2: value2 $VAR1
  VAR3:
    value: value3 $VAR1
    expand: false

使用 expand 关键字将变量配置为可扩展或不可扩展

when

使用 when 配置作业运行的条件。如果未在作业中定义，则默认值为 when:on_success

stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:
  stage: build
  script:
    - make build

cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
    - make test

deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual
  environment: production

cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always

:-	–
`on_success(default)`	仅当早期阶段的所有作业都成功或具有 `allow_failure: true` 时才运行该作业
`manual`	仅在手动触发时运行作业
`always`	无论早期阶段的作业状态如何，都运行作业。也可以用在 `workflow:rules` 中
`on_failure`	仅当早期阶段的至少一项作业失败时才运行该作业
`delayed`	将作业的执行延迟指定的持续时间
`never`	不要运行作业。只能在规则rules部分或工作流中使用：`workflow: rules`

artifacts

使用工件指定要将哪些文件另存为作业 artifacts。作业 artifacts 是作业成功、失败或始终附加到作业的文件和目录的列表

artifacts:paths

路径是相对于项目目录（$CI_PROJECT_DIR）的，不能直接链接到项目目录之外

job:
  artifacts:
    paths:
      - binaries/
      - .config

artifacts:exclude

防止将文件添加到 artifacts 存档中

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/**/*.o

artifacts:expire_in

指定作业 artifacts 在它们过期和被删除之前存储多长时间

1
2
3

job:
  artifacts:
    expire_in: 1 week

‘42’
42 seconds
3 mins 4 sec
2 hrs 20 min
2h20min
6 mos 1 day
47 yrs 6 mos and 4d
3 weeks and 2 days
never

artifacts:expose_as

使用 artifacts:expose_as 关键字在合并请求 UI 中公开作业 artifacts

test:
  script: ["echo 'test' > file.txt"]
  artifacts:
    expose_as: 'artifact 1'
    paths: ['file.txt']

artifacts:name

定义创建的 artifacts 存档的名称。您可以为每个存档指定一个唯一的名称

job:
  artifacts:
    name: "job1-artifacts-file"
    paths:
      - binaries/

artifacts:public

确定作业工件是否应该公开可用

1
2
3

job:
  artifacts:
    public: false

artifacts:reports

收集作业中包含的模板生成的 artifacts

rspec:
  stage: test
  script:
    - bundle install
    - rspec --format RspecJunitFormatter --out rspec.xml
  artifacts:
    reports:
      junit: rspec.xml

artifacts:untracked

将所有 Git 未跟踪文件添加为 artifacts（连同在 artifacts:paths 中定义的路径）

1
2
3

job:
  artifacts:
    untracked: true

artifacts:when

作业失败或尽管失败时上传 artifacts

1
2
3

job:
  artifacts:
    when: on_failure

cache

cache:paths

rspec:
  script:
    - echo "此作业使用缓存"
  cache:
    key: binaries-cache
    paths:
      - binaries/*.apk
      - .config

关键字来选择要缓存的文件或目录

cache:key

为每个缓存提供唯一的标识键。使用相同缓存键的所有作业都使用相同的缓存，包括在不同的管道中

cache-job:
  script:
    - echo "此作业使用缓存"
  cache:
    key: binaries-cache-$CI_COMMIT_REF_SLUG
    paths:
      - binaries/

`cache:key:files`

cache-job:
  script:
    - echo "此作业使用缓存"
  cache:
    key:
      files:
        - Gemfile.lock
        - package.json
    paths:
      - vendor/ruby
      - node_modules

当一个或两个特定文件更改时，使用 cache:key:files 关键字生成新密钥

`cache:key:prefix`

rspec:
  script:
    - echo "此 rspec 作业使用缓存"
  cache:
    key:
      files:
        - Gemfile.lock
      prefix: $CI_JOB_NAME
    paths:
      - vendor/ruby

使用 cache:key:prefix 将前缀与为 cache:key:files 计算的 SHA 结合起来

cache:untracked

rspec:
  script: test
  cache:
    untracked: true
    paths:
      - binaries/

使用 untracked: true 缓存 Git 存储库中所有未跟踪的文件

cache:when

rspec:
  script: rspec
  cache:
    paths:
      - rspec/
    when: 'always'

使用 cache:when 根据作业的状态定义何时保存缓存

:-	–
`on_succes(默认)`	仅当作业成功时才保存缓存
`on_failure`	仅在作业失败时才保存缓存
`always`	始终保存缓存

cache:policy

prepare-dependencies-job:
  stage: build
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: push
  script:
    - echo "此作业仅下载依赖项并构建缓存"
    - echo "正在下载依赖..."

faster-test-job:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - echo "此作业脚本使用缓存，但不更新它"
    - echo "运行测试..."

要更改缓存的上传和下载行为，请使用 cache:policy 关键字

environment

environment:name

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production

为环境设置名称

environment:url

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production
    url: https://prod.example.com

为环境设置 URL

environment:on_stop

关闭（停止）环境可以通过在环境下定义的 on_stop 关键字来实现。它声明运行以关闭环境的不同作业

environment:action

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

:-	–
`start` 默认值	指示作业启动环境。在作业开始后创建的
`prepare`	表示作业只是准备环境。它不会触发部署
`stop`	指示作业停止部署
`verify`	指示作业仅验证环境。它不会触发部署
`access`	指示作业仅访问环境。它不会触发部署

environment:auto_stop_in

review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    auto_stop_in: 1 day

168 hours
7 days
one week
never

auto_stop_in 关键字指定环境的生命周期。当环境到期时，GitLab 会自动停止它

environment:kubernetes

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      namespace: production

使用 kubernetes 关键字将部署配置到与您的项目关联的 Kubernetes 集群

environment:deployment_tier

deploy:
  script: echo
  environment:
    name: customer-portal
    deployment_tier: production

production
staging
testing
development
other

动态 environment

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

image

image:name

1 2	image: name: "registry.example.com/my/image:latest"

作业运行所在的 Docker 镜像的名称。类似于它自己使用的镜像

image:entrypoint

1
2
3

image:
  name: super/sql:experimental
  entrypoint: [""]

作为容器入口点执行的命令或脚本

image:pull_policy

job1:
  script: echo "单一拉动政策"
  image:
    name: ruby:3.0
    pull_policy: if-not-present

job2:
  script: echo "多重拉动政策"
  image:
    name: ruby:3.0
    pull_policy: [always, if-not-present]

运行器用于获取 Docker 映像的拉取策略

needs

needs:artifacts

当作业使用需求时，它不再默认下载先前阶段的所有工件，因为有需求的作业可以在早期阶段完成之前开始

test-job1:
  stage: test
  needs:
    - job: build_job1
      artifacts: true

test-job2:
  stage: test
  needs:
    - job: build_job2
      artifacts: false

test-job3:
  needs:
    - job: build_job1
      artifacts: true
    - job: build_job2
    - build_job3

needs:project

使用 needs:project 从其他管道中的最多五个作业下载工件。工件是从指定参考的最新成功管道下载的。要指定多个作业，请将每个作业作为单独的数组项添加到 needs 关键字下

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: namespace/group/project-name
      job: build-1
      ref: main
      artifacts: true
    - project: namespace/group/project-name-2
      job: build-2
      ref: main
      artifacts: true

needs:pipeline:job

create-artifact:
  stage: build
  script: echo "sample artifact" > artifact.txt
  artifacts:
    paths: [artifact.txt]

child-pipeline:
  stage: test
  trigger:
    include: child.yml
    strategy: depend
  variables:
    PARENT_PIPELINE_ID: $CI_PIPELINE_ID

子管道可以从其父管道中的作业或同一父子管道层次结构中的另一个子管道下载工件

needs:optional

要需要管道中有时不存在的作业，请将 optional: true 添加到需求配置中。如果未定义，则可选：默认为 false

build-job:
  stage: build

test-job1:
  stage: test

test-job2:
  stage: test
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
    - job: test-job1
  environment: production

review-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
  environment: review

needs:pipeline

您可以使用 needs:pipeline 关键字将管道状态从上游管道镜像到桥接作业

upstream_bridge:
  stage: test
  needs:
    pipeline: other/project

only / except

only:refs / except:refs

job1:
  script: echo
  only:
    - main
    - /^issue-.*$/
    - merge_requests

job2:
  script: echo
  except:
    - main
    - /^stable-branch.*$/
    - schedules

使用 only:refs 和 except:refs 关键字来控制何时根据分支名称或管道类型将作业添加到管道

only:variables / except:variables

deploy:
  script: cap staging deploy
  only:
    variables:
      - $RELEASE == "staging"
      - $STAGING

根据 CI/CD 变量的状态，使用 only:variables 或 except:variables 关键字来控制何时将作业添加到管道

only:changes / except:changes

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - branches
    changes:
      - Dockerfile
      - docker/scripts/*
      - dockerfiles/**/*
      - more_scripts/*.{rb,py,sh}
      - "**/*.json"

当 Git 推送事件修改文件时，使用 changes 关键字仅运行作业，或使用 except 跳过作业

only:kubernetes / except:kubernetes

1
2
3

deploy:
  only:
    kubernetes: active

使用 only:kubernetes 或 except:kubernetes 来控制当 Kubernetes 服务在项目中处于活动状态时是否将作业添加到管道中

release

release 参考

:-	–
release:tag_name	发布的 Git 标签
release:tag_message	指定的消息进行注释
release:name	发布名称
release:description	版本的详细描述
release:ref	发布的 ref
release:milestones	每个里程碑的标题
release:released_at	发布准备就绪的日期和时间

release:tag_name

job:
  script: echo "为新标签运行发布作业"
  release:
    tag_name: $CI_COMMIT_TAG
    description: 'Release description'
  rules:
    - if: $CI_COMMIT_TAG

必需的。发布的 Git 标签

release:tag_message

release_job:
  stage: release
  release:
    tag_name: $CI_COMMIT_TAG
    description: 'Release description'
    tag_message: 'Annotated tag message'

如果标签不存在，则新创建的标签将使用 tag_message 指定的消息进行注释

release:name

release_job:
  stage: release
  release:
    name: 'Release $CI_COMMIT_TAG'

发布名称。如果省略，它会填充 release:tag_name 的值

release:description

job:
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: './path/to/CHANGELOG.md'

版本的详细描述

release:ref

发布的 ref，如果发布：tag_name 尚不存在

release:milestones

与版本关联的每个里程碑的标题

release:released_at

1	released_at: '2021-03-15T08:00:00Z'

发布准备就绪的日期和时间

release:assets:links

assets:
  links:
    - name: 'asset1'
      url: 'https://example.com/assets/1'
    - name: 'asset2'
      url: 'https://example.com/assets/2'
      filepath: '/pretty/url/1' # 可选的
      link_type: 'other' # 可选的

使用 release:assets:links 在发布中包含资产链接

rules

rules:if

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH
      when: never
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/
      when: manual
      allow_failure: true
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME

使用 rules:if 子句指定何时将作业添加到管道

rules:changes

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile
      when: manual
      allow_failure: true

使用 rules:changes 通过检查对特定文件的更改来指定何时将作业添加到管道

rules:changes:paths

docker-build-1:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile

docker-build-2:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile

使用 rules:changes 指定仅在更改特定文件时将作业添加到管道，并使用 rules:changes:paths 指定文件

rules:changes:compare_to

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile
        compare_to: 'refs/heads/branch1'

使用 rules:changes:compare_to 指定要比较哪个 ref 来比较 rules:changes:paths 下列出的文件的更改

rules:exists

job:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        - Dockerfile

当存储库中存在某些文件时，使用 exists 运行作业

rules:allow_failure

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
      when: manual
      allow_failure: true

在规则中使用 allow_failure: true 允许作业失败而不停止管道

rules:variables

job:
  variables:
    DEPLOY_VARIABLE: "default-deploy"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:                              # 覆盖定义的 DEPLOY_VARIABLE
        DEPLOY_VARIABLE: "deploy-production"  # 在工作层面
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # 定义一个新变量
  script:
    - echo "以 $DEPLOY_VARIABLE 作为参数运行脚本"
    - echo "如果 $IS_A_FEATURE 存在则运行另一个脚本"

在规则中使用变量来为特定条件定义变量

另见

.gitlab-ci.yml 关键字参考