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 分支提交触发

• after_script
• artifacts
• before_script
• cache
• image
• interruptible
• retry
• services
• tags
• timeout

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

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

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

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

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

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

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

• .pre
• build
• test
• deploy
• .post

stages:
  - build
  - test
  - deploy

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

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 关键字类似于作业中定义的 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:
  script:
    - echo "示例脚本部分"
  after_script:
    - echo "在“script”部分完成后执行此命令"

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

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

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

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

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:
  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 作业。然后将内容发布为网站

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

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

job:
  tags:
    - ruby
    - postgres

使用标签从项目可用的所有运行器列表中选择特定运行器

job1:
  script: "bundle exec rspec"

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

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

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

test:
  script: rspec
  timeout: 3h 30m

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

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

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

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

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

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

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

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 关键字在合并请求 UI 中公开作业 artifacts

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

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

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

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

job:
  artifacts:
    public: false

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

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

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

job:
  artifacts:
    untracked: true

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

job:
  artifacts:
    when: on_failure

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

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

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

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

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

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

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 关键字

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

为环境设置名称

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

为环境设置 URL

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

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

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 会自动停止它

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

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

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

• production
• staging
• testing
• development
• other

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

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

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

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

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

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 映像的拉取策略

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

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

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:pipeline 关键字将管道状态从上游管道镜像到桥接作业

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

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

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

deploy:
  only:
    kubernetes: active

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

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

必需的。发布的 Git 标签

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

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

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

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

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

版本的详细描述

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

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

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

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

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 在发布中包含资产链接

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 子句指定何时将作业添加到管道

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

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

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

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

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 存在则运行另一个脚本"

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