diff --git a/docs/gitlab-ci.md b/docs/gitlab-ci.md index b4c9ff56..7cf1baf3 100644 --- a/docs/gitlab-ci.md +++ b/docs/gitlab-ci.md @@ -8,6 +8,17 @@ GitLab CI/CD 备忘清单 ### 介绍 +创建并运行您的第一个 GitLab `CI/CD` 管道，在开始之前，请确保您拥有： + +- GitLab 中您想要使用 CI/CD 的项目 +- 项目的维护者或所有者角色 + +如果您没有项目，可以在 上免费创建一个公共项目 + +- 在存储库的根目录下创建一个 `.gitlab-ci.yml` 文件。该文件是您定义 `CI/CD` 作业的地方 +- 转到`Settings` > `CI/CD` 并展开运行程序，只要您至少有一个运行器处于活动状态，旁边有一个绿色圆圈，您就有一个运行器可以处理您的工作 + + 关键字 --- @@ -111,7 +122,7 @@ include: ``` ### include:project - + 要在同一个 GitLab 实例上包含来自另一个私有项目的文件，请使用 `include:project` 和 `include:file` @@ -150,6 +161,7 @@ include: ``` ### include:template + 使用 `include:template` 来包含 `.gitlab-ci.yml` 模板 @@ -244,13 +256,13 @@ job1: 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" + - echo "以 $DEPLOY_VARIABLE 作为参数运行脚本" + - echo "如果 $IS_A_FEATURE 存在则运行另一个脚本" job2: script: - - echo "Run script with $DEPLOY_VARIABLE as an argument" - - echo "Run another script if $IS_A_FEATURE exists" + - echo "以 $DEPLOY_VARIABLE 作为参数运行脚本" + - echo "如果 $IS_A_FEATURE 存在则运行另一个脚本" ``` ### workflow:rules @@ -289,7 +301,7 @@ job: ``` ### allow_failure - + 确定管道是否应在作业失败时继续运行 @@ -319,14 +331,14 @@ job3: ```yml test_job_1: script: - - echo "运行导致退出代码 1 的脚本。此作业失败" + - echo "退出代码 1 的脚本。此作业失败" - exit 1 allow_failure: exit_codes: 137 test_job_2: script: - - echo "运行导致退出代码 137 的脚本。允许此作业失败" + - echo "退出代码 137 的脚本允许此作业失败" - exit 137 allow_failure: exit_codes: @@ -334,6 +346,25 @@ test_job_2: - 255 ``` +### dast_configuration + + +```yml +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` 命令之前运行，但在工件恢复之后运行 @@ -341,79 +372,610 @@ test_job_2: ```yml job: before_script: - - echo "在任何“script:”命令之前执行此命令。" + - echo "在任何“script:”命令之前执行此命令" script: - - echo "此命令在作业的“before_script”命令之后执行" + - echo "“before_script”命令之后执行" ``` ### coverage -### dast_configuration +```yml +job1: + script: rspec + coverage: '/Code coverage: \d+\.\d+/' +``` -### dependencies +使用自定义正则表达式的覆盖率来配置如何从作业输出中提取代码覆盖率 ### extends + + +```yml +.tests: + script: rake test + stage: test + only: + refs: + - branches + +rspec: + extends: .tests + script: rake rspec + only: + variables: + - $RSPEC +``` + +使用 `extends` 重用配置部分。 它是 YAML 锚点的替代品，并且更加灵活和可读 + +### dependencies + + +```yml +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` 关键字的继承 + +```yml +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 控制全局变量关键字的继承 + +```yml +variables: + VARIABLE1: "这是变量 1" + VARIABLE2: "这是变量 2" + VARIABLE3: "这是变量 3" + +job1: + script: echo "该作业不继承任何全局变量" + inherit: + variables: false + +job2: + script: echo "此作业仅继承列出的两个全局变量。它不继承“VARIABLE3”" + inherit: + variables: + - VARIABLE1 + - VARIABLE2 +``` + ### interruptible +```yml +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 +```yml +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 + + +```yml +test: + script: rspec + parallel: 5 +``` + +使用 `parallel` 在单个管道中并行多次运行作业 #### parallel:matrix +```yml +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 -### retry +```yml +deploy-to-production: + script: deploy + resource_group: production +``` -#### retry:when - -### script - -### secrets - -#### secrets:vault - -#### secrets:file - -### services - -#### service:pull_policy - -### stage - -#### stage: .pre - -#### stage: .post +创建一个资源组，以确保作业在同一项目的不同管道之间互斥 ### tags +```yml +job: + tags: + - ruby + - postgres +``` + +使用标签从项目可用的所有运行器列表中选择特定运行器 + +### retry + +```yml +test: + script: rspec + retry: 2 +``` + +使用 `retry` 配置作业失败时重试的次数。如果未定义，则默认为 `0`，并且作业不会重试 + +#### retry:when + +```yml +test: + script: rspec + retry: + max: 2 + when: runner_system_failure +``` + +使用 `retry:when` 和 `retry:max` 来重试特定失败案例的作业。 `retry:max` 是最大重试次数，和`retry`一样，可以是0、1、2 + +### script + +```yml +job1: + script: "bundle exec rspec" + +job2: + script: + - uname -a + - bundle exec rspec +``` + +使用脚本指定运行器执行的命令 + +### secrets + + +此关键字必须与 `secrets:vault` 一起使用 + +#### secrets:vault + +使用 `secrets:vault` 指定 HashiCorp Vault 提供的秘密 + +```yml +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 变量 + +```yml +job: + secrets: + DATABASE_PASSWORD: + vault: production/db/password@ops + file: false +``` + ### timeout +```yml +build: + script: build.sh + timeout: 3 hours 30 minutes + +test: + script: rspec + timeout: 3h 30m +``` + +为特定作业配置超时。 如果作业运行时间超过超时时间，则作业失败 + +### services + + +使用服务指定额外的 `Docker` 映像以在其中运行脚本 + +```yml +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` 映像的拉取策略 + +```yml +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 + + +```yml +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 + +```yml +stages: + - build + - test + +job1: + stage: build + script: + - echo "该作业在构建阶段运行" + +first-job: + stage: .pre + script: + - echo "该作业在 .pre 阶段运行，在所有其他阶段之前" + +job2: + stage: test + script: + - echo "该作业在测试阶段运行" +``` + +#### stage: .post + +```yml +stages: + - build + - test + +job1: + stage: build + script: + - echo "该作业在构建阶段运行" + +last-job: + stage: .post + script: + - echo "该作业在 .post 阶段运行，在所有其他阶段之后" + +job2: + stage: test + script: + - echo "该作业在测试阶段运行" +``` + ### trigger + + +声明一个作业是一个“触发作业” + +```yml +trigger-multi-project-pipeline: + trigger: my-group/my-project +``` #### trigger:include +```yml +trigger-child-pipeline: + trigger: + include: path/to/child-pipeline.gitlab-ci.yml +``` + +声明作业是启动子管道的“触发器作业” + #### trigger:project +```yml +trigger-multi-project-pipeline: + trigger: + project: my-group/my-project +``` + +声明作业是启动多项目管道的“触发器作业” + #### trigger:strategy +```yml +trigger-multi-project-pipeline: + trigger: + project: my-group/my-project + branch: development +``` + +强制触发作业等待下游管道完成后再标记为成功 + #### trigger:forward +```yml +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 变量是传递给作业的可配置值。使用变量创建自定义变量 + +```yml +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 +```yml +variables: + DEPLOY_ENVIRONMENT: + description: "部署目标。 如果需要，将此变量更改为“canary”或“production”" + value: "staging" +``` + #### variables:expand +```yml +variables: + VAR1: value1 + VAR2: value2 $VAR1 + VAR3: + value: value3 $VAR1 + expand: false +``` + +使用 `expand` 关键字将变量配置为可扩展或不可扩展 + ### when +使用 `when` 配置作业运行的条件。如果未在作业中定义，则默认值为 `when:on_success` + +```yml +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](#rules)部分或工作流中使用：`workflow: rules` + + artifacts --- @@ -540,102 +1102,675 @@ cache ### cache:paths +```yml +rspec: + script: + - echo "此作业使用缓存" + cache: + key: binaries-cache + paths: + - binaries/*.apk + - .config +``` + +关键字来选择要缓存的文件或目录 + ### cache:key + + +为每个缓存提供唯一的标识键。 使用相同缓存键的所有作业都使用相同的缓存，包括在不同的管道中 + +```yml +cache-job: + script: + - echo "此作业使用缓存" + cache: + key: binaries-cache-$CI_COMMIT_REF_SLUG + paths: + - binaries/ +``` #### `cache:key:files` +```yml +cache-job: + script: + - echo "此作业使用缓存" + cache: + key: + files: + - Gemfile.lock + - package.json + paths: + - vendor/ruby + - node_modules +``` + +当一个或两个特定文件更改时，使用 `cache:key:files` 关键字生成新密钥 + #### `cache:key:prefix` +```yml +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 +```yml +rspec: + script: test + cache: + untracked: true + paths: + - binaries/ +``` + +使用 `untracked: true` 缓存 Git 存储库中所有未跟踪的文件 + ### cache:when +```yml +rspec: + script: rspec + cache: + paths: + - rspec/ + when: 'always' +``` + +使用 `cache:when` 根据作业的状态定义何时保存缓存 + +:- | -- +:- | -- +`on_succes(默认)` | 仅当作业成功时才保存缓存 +`on_failure` | 仅在作业失败时才保存缓存 +`always` | 始终保存缓存 + ### cache:policy +```yml +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 +```yml +deploy to production: + stage: deploy + script: git push production HEAD:main + environment: + name: production +``` + +为环境设置名称 + ### environment:url +```yml +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 +```yml +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 +```yml +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 +```yml +deploy: + stage: deploy + script: make deploy-app + environment: + name: production + kubernetes: + namespace: production +``` + +使用 `kubernetes` 关键字将部署配置到与您的项目关联的 `Kubernetes` 集群 + ### environment:deployment_tier -### Dynamic environments +```yml +deploy: + script: echo + environment: + name: customer-portal + deployment_tier: production +``` + +- `production` +- `staging` +- `testing` +- `development` +- `other` + + +### 动态 environment + +```yml +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 +```yml +image: + name: "registry.example.com/my/image:latest" +``` + + +作业运行所在的 Docker 镜像的名称。类似于它自己使用的镜像 + ### image:entrypoint +```yml +image: + name: super/sql:experimental + entrypoint: [""] +``` + +作为容器入口点执行的命令或脚本 + ### image:pull_policy +```yml +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 +当作业使用需求时，它不再默认下载先前阶段的所有工件，因为有需求的作业可以在早期阶段完成之前开始 + +```yml +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 关键字下 + +```yml +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 +```yml +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` + +```yml +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` 关键字将管道状态从上游管道镜像到桥接作业 + +```yml +upstream_bridge: + stage: test + needs: + pipeline: other/project +``` + only / except --- ### only:refs / except:refs + + +```yml +job1: + script: echo + only: + - main + - /^issue-.*$/ + - merge_requests + +job2: + script: echo + except: + - main + - /^stable-branch.*$/ + - schedules +``` + +使用 `only:refs` 和 `except:refs` 关键字来控制何时根据分支名称或管道类型将作业添加到管道 ### only:variables / except:variables +```yml +deploy: + script: cap staging deploy + only: + variables: + - $RELEASE == "staging" + - $STAGING +``` + +根据 CI/CD 变量的状态，使用 only:variables 或 except:variables 关键字来控制何时将作业添加到管道 + ### only:changes / except:changes + + +```yml +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 +```yml +deploy: + only: + kubernetes: active +``` + +使用 `only:kubernetes` 或 `except:kubernetes` 来控制当 `Kubernetes` 服务在项目中处于活动状态时是否将作业添加到管道中 + release --- +### release 参考 + +:- | -- +:- | -- +[release:tag_name](#releasetag_name) | 发布的 Git 标签 +[release:tag_message](#releasetag_message) | 指定的消息进行注释 +[release:name](#releasename) | 发布名称 +[release:description](#releasedescription) | 版本的详细描述 +[release:ref](#releaseref) | 发布的 ref +[release:milestones](#releasemilestones) | 每个里程碑的标题 +[release:released_at](#releasereleased_at) | 发布准备就绪的日期和时间 + ### release:tag_name +```yml +job: + script: echo "为新标签运行发布作业" + release: + tag_name: $CI_COMMIT_TAG + description: 'Release description' + rules: + - if: $CI_COMMIT_TAG +``` + +必需的。发布的 Git 标签 + ### release:tag_message +```yml +release_job: + stage: release + release: + tag_name: $CI_COMMIT_TAG + description: 'Release description' + tag_message: 'Annotated tag message' +``` + +如果标签不存在，则新创建的标签将使用 `tag_message` 指定的消息进行注释 + ### release:name +```yml +release_job: + stage: release + release: + name: 'Release $CI_COMMIT_TAG' +``` + +发布名称。如果省略，它会填充 `release:tag_name` 的值 + ### release:description +```yml +job: + release: + tag_name: ${MAJOR}_${MINOR}_${REVISION} + description: './path/to/CHANGELOG.md' +``` + +版本的详细描述 + ### release:ref +发布的 ref，如果发布：`tag_name` 尚不存在 + ### release:milestones +与版本关联的每个里程碑的标题 + ### release:released_at +```yml +released_at: '2021-03-15T08:00:00Z' +``` + +发布准备就绪的日期和时间 + ### release:assets:links +```yml +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 +```yml +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 + + +```yml +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 +```yml +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 +```yml +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 +```yml +job: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - exists: + - Dockerfile +``` + +当存储库中存在某些文件时，使用 `exists` 运行作业 + ### rules:allow_failure +```yml +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 + +```yml +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 关键字参考](https://docs.gitlab.com/ee/ci/yaml/)