GitLab CI/CD 备忘清单 === 本备忘单总结了 [GitLab CI/CD](https://docs.gitlab.com/ee/ci/yaml/#default) 常用的配置说明，以供快速参考 入门 --- ### 介绍 关键字 --- ### 关键字 关键字 | 描述 :-- | -- [default](#default) | 工作关键字的自定义默认值 [#](https://docs.gitlab.com/ee/ci/yaml/#default) [include](#include) | 从其他 YAML 文件导入配置 [#](https://docs.gitlab.com/ee/ci/yaml/#include) [stages](#stages) | 管道阶段的名称和顺序 [#](https://docs.gitlab.com/ee/ci/yaml/#stages) [variables](#variables) | 为管道中的所有作业定义 CI/CD 变量 [#](https://docs.gitlab.com/ee/ci/yaml/#variables) [workflow](#workflow) | 控制运行什么类型的管道 [#](https://docs.gitlab.com/ee/ci/yaml/#workflow) ### 关键字 关键字 | 描述 :-- | -- [after_script](#after_script) | 覆盖一组在作业之后执行的命令 [#](https://docs.gitlab.com/ee/ci/yaml/#after_script) [allow_failure](#allow_failure) | 允许作业失败。失败的作业不会导致管道失败 [#](https://docs.gitlab.com/ee/ci/yaml/#allow_failure) [artifacts](#artifacts) | 成功时附加到作业的文件和目录列表 [#](https://docs.gitlab.com/ee/ci/yaml/#artifacts) [before_script](#before_script) | 覆盖在作业之前执行的一组命令 [#](https://docs.gitlab.com/ee/ci/yaml/#before_script) [cache](#cache) | 应在后续运行之间缓存的文件列表 [#](https://docs.gitlab.com/ee/ci/yaml/#cache) [coverage](#coverage) | 给定作业的代码覆盖率设置 [#](https://docs.gitlab.com/ee/ci/yaml/#coverage) [dast_configuration](#dast_configuration) | 在作业级别使用 DAST 配置文件中的配置 [#](https://docs.gitlab.com/ee/ci/yaml/#dast_configuration) [dependencies](#dependencies) | 通过提供要从中获取工件的作业列表来限制将哪些工件传递给特定作业 [#](https://docs.gitlab.com/ee/ci/yaml/#dependencies) [environment](#environment) | 作业部署到的环境的名称 [#](https://docs.gitlab.com/ee/ci/yaml/#environment) [except](#only--except) | 控制何时不创建作业 [#](https://docs.gitlab.com/ee/ci/yaml/#only--except) [extends](#extends) | 此作业继承自的配置条目 [#](https://docs.gitlab.com/ee/ci/yaml/#extends) [image](#image) | 使用 Docker 镜像 [#](https://docs.gitlab.com/ee/ci/yaml/#image) [inherit](#inherit) | 选择所有作业继承的全局默认值 [#](https://docs.gitlab.com/ee/ci/yaml/#inherit) [interruptible](#interruptible) | 定义作业是否可以在被较新的运行冗余时取消 [#](https://docs.gitlab.com/ee/ci/yaml/#interruptible) [needs](#needs) | 在阶段排序之前执行作业 [#](https://docs.gitlab.com/ee/ci/yaml/#needs) [only](#only--except) | 控制何时创建作业 [#](https://docs.gitlab.com/ee/ci/yaml/#only--except) [pages](#pages) | 上传作业的结果以与 GitLab Pages 一起使用 [#](https://docs.gitlab.com/ee/ci/yaml/#pages) [parallel](#parallel) | 应并行运行多少个作业实例 [#](https://docs.gitlab.com/ee/ci/yaml/#parallel) [release](#release) | 指示运行器生成释放对象 [#](https://docs.gitlab.com/ee/ci/yaml/#release) [resource_group](#resource_group) | 限制作业并发 [#](https://docs.gitlab.com/ee/ci/yaml/#resource_group) [retry](#retry) | 发生故障时可以自动重试作业的时间和次数 [#](https://docs.gitlab.com/ee/ci/yaml/#retry) [rules](#rules) | 用于评估和确定作业的选定属性以及是否创建的条件列表 [#](https://docs.gitlab.com/ee/ci/yaml/#rules) [script](#script) | 由运行器执行的 Shell 脚本 [#](https://docs.gitlab.com/ee/ci/yaml/#script) [secrets](#secrets) | CI/CD 保密工作需要 [#](https://docs.gitlab.com/ee/ci/yaml/#secrets) [services](#services) | 使用 Docker 服务映像 [#](https://docs.gitlab.com/ee/ci/yaml/#services) [stage](#stage) | 定义作业阶段 [#](https://docs.gitlab.com/ee/ci/yaml/#stage) [tags](#tags) | 用于选择跑步者的标签列表 [#](https://docs.gitlab.com/ee/ci/yaml/#tags) [timeout](#timeout) | 定义优先于项目范围设置的自定义作业级超时 [#](https://docs.gitlab.com/ee/ci/yaml/#timeout) [trigger](#trigger) | 定义下游管道触发器 [#](https://docs.gitlab.com/ee/ci/yaml/#trigger) [variables](#variables) | 在作业级别定义作业变量 [#](https://docs.gitlab.com/ee/ci/yaml/#variables) [when](#when) | 何时运行作业 [#](https://docs.gitlab.com/ee/ci/yaml/#when) 全局关键词 --- ### default - [after_script](#after_script) - [artifacts](#artifacts) - [before_script](#before_script) - [cache](#cache) - [image](#image) - [interruptible](#interruptible) - [retry](#retry) - [services](#services) - [tags](#tags) - [timeout](#timeout) 示例 ```yml 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 在 `11.4` 中移至 `GitLab` 免费版，使用 `include` 将外部 `YAML` 文件包含在您的 `CI/CD` 配置中 ```yml include: - local: '/temp/.gitlab-ci-template.yml' ``` ### include:local 使用 `include:local` 包含与 `.gitlab-ci.yml` 文件位于同一存储库中的文件 ```yml include: - local: '/temp/.gitlab-ci-template.yml' ``` ### include:project 要在同一个 GitLab 实例上包含来自另一个私有项目的文件，请使用 `include:project` 和 `include:file` ```yml 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`： ```yml 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 使用带有完整 `URL` 的 `include:remote` 来包含来自不同位置的文件 ```yml include: - remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml' ``` ### include:template 使用 `include:template` 来包含 `.gitlab-ci.yml` 模板 ```yml # 文件来自 GitLab 模板集合 include: - template: Auto-DevOps.gitlab-ci.yml ``` 多个 `include:template` 文件： ```yml include: - template: Android-Fastlane.gitlab-ci.yml - template: Auto-DevOps.gitlab-ci.yml ``` ### stages 使用阶段来定义包含作业组的阶段。如果 `.gitlab-ci.yml` 文件中未定义阶段，则默认管道阶段为： - [.pre](#stage-pre) - build - test - deploy - [.post](#stage-post) --- ```yml stages: - build - test - deploy ``` workflow --- ### workflow:name 您可以在 workflow: 中使用 name 来定义管道的名称 ```yml workflow: name: '分支管道：$CI_COMMIT_BRANCH' ``` 根据管道条件具有不同管道名称的配置： ```yml 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` 中使用变量来定义特定管道条件的变量 ```yml 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 "Run script with $DEPLOY_VARIABLE as an argument" - echo "Run another script if $IS_A_FEATURE exists" job2: script: - echo "Run script with $DEPLOY_VARIABLE as an argument" - echo "Run another script if $IS_A_FEATURE exists" ``` ### workflow:rules 工作流(workflow)中的 `rules` 关键字类似于作业中定义的 [`rules`](#rules)，但控制是否创建整个管道 - [rules: if](#rulesif) - [rules: changes](#ruleschanges) - [rules: exists](#rulesexists) - [when](#when) - [variables](#workflowrulesvariables) ```yml 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 在每个作业（包括失败的作业）**之后**运行的命令数组 ```yml job: script: - echo "示例脚本部分" after_script: - echo "在“script”部分完成后执行此命令" ``` ### allow_failure 确定管道是否应在作业失败时继续运行 ```yml 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 ```yml 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 ``` ### before_script 在每个作业的 `script` 命令之前运行，但在工件恢复之后运行 ```yml job: before_script: - echo "在任何“script:”命令之前执行此命令。" script: - echo "此命令在作业的“before_script”命令之后执行" ``` ### coverage ### dast_configuration ### dependencies ### extends ### inherit #### inherit:default #### inherit:variables ### interruptible ### pages ### parallel #### parallel:matrix ### resource_group ### retry #### retry:when ### script ### secrets #### secrets:vault #### secrets:file ### services #### service:pull_policy ### stage #### stage: .pre #### stage: .post ### tags ### timeout ### trigger #### trigger:include #### trigger:project #### trigger:strategy #### trigger:forward ### variables #### variables:description #### variables:expand ### when artifacts --- 使用工件指定要将哪些文件另存为作业 artifacts。作业 artifacts 是作业成功、失败或始终附加到作业的文件和目录的列表 ### artifacts:paths 路径是相对于项目目录（$CI_PROJECT_DIR）的，不能直接链接到项目目录之外 ```yml job: artifacts: paths: - binaries/ - .config ``` ### artifacts:exclude 防止将文件添加到 artifacts 存档中 ```yml artifacts: paths: - binaries/ exclude: - binaries/**/*.o ``` ### artifacts:expire_in 指定作业 artifacts 在它们过期和被删除之前存储多长时间 ```yml 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 ```yml test: script: ["echo 'test' > file.txt"] artifacts: expose_as: 'artifact 1' paths: ['file.txt'] ``` ### artifacts:name 定义创建的 `artifacts` 存档的名称。您可以为每个存档指定一个唯一的名称 ```yml job: artifacts: name: "job1-artifacts-file" paths: - binaries/ ``` ### artifacts:public 确定作业工件是否应该公开可用 ```yml job: artifacts: public: false ``` ### artifacts:reports 收集作业中包含的模板生成的 `artifacts` ```yml rspec: stage: test script: - bundle install - rspec --format RspecJunitFormatter --out rspec.xml artifacts: reports: junit: rspec.xml ``` ### artifacts:untracked 将所有 Git 未跟踪文件添加为 `artifacts`（连同在 `artifacts:paths` 中定义的路径） ```yml job: artifacts: untracked: true ``` ### artifacts:when 作业失败或尽管失败时上传 `artifacts` ```yml job: artifacts: when: on_failure ``` cache --- ### cache:paths ### cache:key #### `cache:key:files` #### `cache:key:prefix` ### cache:untracked ### cache:when ### cache:policy environment --- ### environment:name ### environment:url ### environment:on_stop ### environment:action ### environment:auto_stop_in ### environment:kubernetes ### environment:deployment_tier ### Dynamic environments image --- ### image:name ### image:entrypoint ### image:pull_policy needs --- ### needs:artifacts ### needs:project ### needs:pipeline:job ### needs:optional ### needs:pipeline only / except --- ### only:refs / except:refs ### only:variables / except:variables ### only:changes / except:changes ### only:kubernetes / except:kubernetes release --- ### release:tag_name ### release:tag_message ### release:name ### release:description ### release:ref ### release:milestones ### release:released_at ### release:assets:links rules --- ### rules:if ### rules:changes #### rules:changes:paths #### rules:changes:compare_to ### rules:exists ### rules:allow_failure ### rules:variables