diff --git a/docs/gitlab-ci.md b/docs/gitlab-ci.md new file mode 100644 index 0000000..b4c9ff5 --- /dev/null +++ b/docs/gitlab-ci.md @@ -0,0 +1,641 @@ +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) + +### 关键字 +<!--rehype:wrap-class=col-span-2--> + +关键字 | 描述 +:-- | -- +[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 +<!--rehype:wrap-class=row-span-3--> + +- [after_script](#after_script) +- [artifacts](#artifacts) +- [before_script](#before_script) +- [cache](#cache) +- [image](#image) +- [interruptible](#interruptible) +- [retry](#retry) +- [services](#services) +- [tags](#tags) +- [timeout](#timeout) +<!--rehype:className=cols-3--> + +示例 + +```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 +<!--rehype:wrap-class=row-span-2--> + +要在同一个 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) +<!--rehype:className=cols-2--> + +--- + +```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 +<!--rehype:wrap-class=col-span-2 row-span-2--> + +您可以在 `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) +<!--rehype:className=cols-2--> + +```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 +<!--rehype:wrap-class=row-span-2--> + +确定管道是否应在作业失败时继续运行 + +```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 +<!--rehype:className=cols-2--> + +### 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