Help us learn about your current experience with the documentation. Take the survey.

CI/CD 变量

使用 CI/CD 变量来设置 Auto DevOps 域名、提供自定义 Helm chart，或扩展你的应用程序。

构建和部署变量

使用这些变量来自定义和部署你的构建。

CI/CD 变量 描述
ADDITIONAL_HOSTS 以逗号分隔的完整域名列表，添加到 Ingress hosts 中。
<ENVIRONMENT>_ADDITIONAL_HOSTS 对于特定环境，以逗号分隔的完整域名列表，添加到 Ingress hosts 中。此变量优先于 ADDITIONAL_HOSTS。
AUTO_BUILD_IMAGE_VERSION 自定义用于 build 作业的镜像版本。参见 版本列表。
AUTO_DEPLOY_IMAGE_VERSION 自定义用于 Kubernetes 部署作业的镜像版本。参见 版本列表。
AUTO_DEVOPS_ATOMIC_RELEASE Auto DevOps 默认使用 --atomic 进行 Helm 部署。将此变量设置为 false 可禁用 --atomic 的使用。
AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER 使用 Cloud Native Buildpacks 构建时使用的构建器。默认构建器是 heroku/buildpacks:22。更多详情。
AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS 传递给 docker build 命令的额外参数。使用引号不会阻止单词分割。更多详情。
AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES 逗号分隔的 CI/CD 变量名列表，将转发到构建环境（buildpack 构建器或 docker build）。
AUTO_DEVOPS_BUILD_IMAGE_CNB_PORT 在 GitLab 15.0 及更高版本中，生成的 Docker 暴露的端口。设置为 false 可防止暴露任何端口。默认为 5000。
AUTO_DEVOPS_BUILD_IMAGE_CONTEXT 用于设置 Dockerfile 和 Cloud Native Buildpacks 的构建上下文目录。默认为根目录。
AUTO_DEVOPS_CHART 用于部署应用程序的 Helm Chart。默认为 GitLab 提供的 chart。
AUTO_DEVOPS_CHART_REPOSITORY 用于搜索 charts 的 Helm Chart 仓库。默认为 https://charts.gitlab.io。
AUTO_DEVOPS_CHART_REPOSITORY_NAME 用于设置 Helm 仓库名称。默认为 gitlab。
AUTO_DEVOPS_CHART_REPOSITORY_USERNAME 用于设置连接到 Helm 仓库的用户名。默认无凭据。同时设置 AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD。
AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD 用于设置连接到 Helm 仓库的密码。默认无凭据。同时设置 AUTO_DEVOPS_CHART_REPOSITORY_USERNAME。
AUTO_DEVOPS_CHART_REPOSITORY_PASS_CREDENTIALS 设置为非空值以启用将 Helm 仓库凭据转发到 chart 服务器，当 chart 工件位于与仓库不同的主机上时。
AUTO_DEVOPS_CHART_REPOSITORY_INSECURE 设置为非空值以在 Helm 命令中添加 --insecure-skip-tls-verify 参数。默认情况下，Helm 使用 TLS 验证。
AUTO_DEVOPS_CHART_CUSTOM_ONLY 设置为非空值以仅使用自定义 chart。默认情况下，chart 会从 GitLab 下载最新版本。
AUTO_DEVOPS_CHART_VERSION 设置部署 chart 的版本。默认为最新可用版本。
AUTO_DEVOPS_COMMON_NAME 从 GitLab 15.5 开始，设置为有效的域名以自定义 TLS 证书的通用名称。默认为 le-$CI_PROJECT_ID.$KUBE_INGRESS_BASE_DOMAIN。设置为 false 可不在 Ingress 上设置此替代主机。
AUTO_DEVOPS_DEPLOY_DEBUG 如果存在此变量，Helm 将输出调试日志。
AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N> 从 auto-deploy-image v1.0.0 开始，如果存在此变量，将强制部署 chart 的新主要版本。更多信息，参见 忽略警告并继续部署。
BUILDPACK_URL 完整的 Buildpack URL。必须指向 Pack 支持的 URL。
CANARY_ENABLED 用于定义 金丝雀环境的部署策略。
BUILDPACK_VOLUMES 指定一个或多个 要挂载的 Buildpack 卷。使用管道符 `
CANARY_PRODUCTION_REPLICAS 在生产环境中为 金丝雀部署 部署的金丝雀副本数。优先于 CANARY_REPLICAS。默认为 1。
CANARY_REPLICAS 为 金丝雀部署 部署的金丝雀副本数。默认为 1。
CI_APPLICATION_REPOSITORY 正在构建或部署的容器镜像的仓库，$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG。更多详情，阅读 自定义容器镜像。
CI_APPLICATION_TAG 正在构建或部署的容器镜像的标签，$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG。更多详情，阅读 自定义容器镜像。
DAST_AUTO_DEPLOY_IMAGE_VERSION 自定义用于在默认分支上进行 DAST 部署的镜像版本。通常应与 AUTO_DEPLOY_IMAGE_VERSION 相同。参见 版本列表。
DOCKERFILE_PATH 允许覆盖 构建阶段的默认 Dockerfile 路径。
HELM_RELEASE_NAME 允许覆盖 helm 发布名称。可用于在将多个项目部署到单个命名空间时分配唯一的发布名称。
HELM_UPGRADE_VALUES_FILE 允许覆盖 helm upgrade values 文件。默认为 .gitlab/auto-deploy-values.yaml。
HELM_UPGRADE_EXTRA_ARGS 允许在部署应用程序时在 helm upgrade 命令中添加额外选项。使用引号不会阻止单词分割。
INCREMENTAL_ROLLOUT_MODE 如果存在，可用于启用 生产环境的逐步部署。设置为 manual 用于手动部署作业，或设置为 timed 用于自动部署作业，每次间隔 5 分钟。
K8S_SECRET_* 任何以 K8S_SECRET_ 为前缀的变量，都会被 Auto DevOps 作为环境变量提供给已部署的应用程序。
KUBE_CONTEXT 可用于从 KUBECONFIG 中选择要使用的上下文。当 KUBE_CONTEXT 为空时，使用 KUBECONFIG 中的默认上下文（如果存在）。在使用 Kubernetes agent 时必须选择一个上下文。
KUBE_INGRESS_BASE_DOMAIN 可用于为每个集群设置域名。更多信息，参见 集群域名。
KUBE_NAMESPACE 用于部署的命名空间。在使用基于证书的集群时，此值不应被直接覆盖。
KUBECONFIG 用于部署的 kubeconfig。用户提供的值优先于 GitLab 提供的值。
PRODUCTION_REPLICAS 在生产环境中部署的副本数。优先于 REPLICAS，默认为 1。对于零停机升级，设置为 2 或更大。
REPLICAS 要部署的副本数。默认为 1。修改此变量而不是 修改 replicaCount。
ROLLOUT_RESOURCE_TYPE 使用自定义 Helm chart 时，允许指定正在部署的资源类型。默认值为 deployment。
ROLLOUT_STATUS_DISABLED 用于禁用部署状态检查，因为它不支持所有资源类型，例如 cronjob。
STAGING_ENABLED 用于定义 暂存和生产环境的部署策略。
TRACE 设置为任何值以使 Helm 命令产生详细输出。您可以使用此设置来帮助诊断 Auto DevOps 部署问题。

数据库变量

从 GitLab 16.0 开始，POSTGRES_ENABLED 不再默认设置。

使用这些变量将 CI/CD 与 PostgreSQL 数据库集成。

CI/CD 变量 描述
DB_INITIALIZE 用于指定运行以初始化应用程序 PostgreSQL 数据库的命令。在应用程序 pod 内运行。
DB_MIGRATE 用于指定运行以迁移应用程序 PostgreSQL 数据库的命令。在应用程序 pod 内运行。
POSTGRES_ENABLED 是否启用 PostgreSQL。设置为 true 以启用 PostgreSQL 的自动部署。
POSTGRES_USER PostgreSQL 用户。默认为 user。设置它以使用自定义用户名。
POSTGRES_PASSWORD PostgreSQL 密码。默认为 testing-password。设置它以使用自定义密码。
POSTGRES_DB PostgreSQL 数据库名称。默认为 $CI_ENVIRONMENT_SLUG 的值。设置它以使用自定义数据库名称。
POSTGRES_VERSION 要使用的 postgres Docker 镜像 的标签。测试和部署默认为 9.6.16。如果 AUTO_DEVOPS_POSTGRES_CHANNEL 设置为 1，部署使用默认版本 9.6.2。
POSTGRES_HELM_UPGRADE_VALUES_FILE 使用 auto-deploy-image v2 时，此变量允许覆盖 PostgreSQL 的 helm upgrade values 文件。默认为 .gitlab/auto-deploy-postgres-values.yaml。
POSTGRES_HELM_UPGRADE_EXTRA_ARGS 使用 auto-deploy-image v2 时，此变量允许在部署应用程序时在 helm upgrade 命令中添加额外的 PostgreSQL 选项。使用引号不会阻止单词分割。
POSTGRES_CHART_REPOSITORY 用于搜索 PostgreSQL chart 的 Helm Chart 仓库。默认为 https://raw.githubusercontent.com/bitnami/charts/eb5f9a9513d987b519f0ecd732e7031241c50328/bitnami。
POSTGRES_CHART_VERSION 用于 PostgreSQL chart 的 Helm Chart 版本。默认为 8.2.1。

作业跳过变量

使用这些变量来跳过特定类型的 CI/CD 作业。被跳过时，CI/CD 作业不会被创建或运行。

作业名称 CI/CD 变量 GitLab 版本 描述
.fuzz_base COVFUZZ_DISABLED 了解更多 关于 .fuzz_base 如何为您的作业提供功能。如果值为 "true"，则不会创建该作业。
apifuzzer_fuzz API_FUZZING_DISABLED 如果值为 "true"，则不会创建该作业。
build BUILD_DISABLED 如果存在该变量，则不会创建该作业。
build_artifact BUILD_DISABLED 如果存在该变量，则不会创建该作业。
brakeman-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
canary CANARY_ENABLED 如果存在该变量，则会创建此手动作业。
code_intelligence CODE_INTELLIGENCE_DISABLED 如果存在该变量，则不会创建该作业。
code_quality CODE_QUALITY_DISABLED 如果值为 "true"，则不会创建该作业。
container_scanning CONTAINER_SCANNING_DISABLED 如果值为 "true"，则不会创建该作业。
dast DAST_DISABLED 如果值为 "true"，则不会创建该作业。
dast_environment_deploy DAST_DISABLED_FOR_DEFAULT_BRANCH 或 DAST_DISABLED 如果值为 "true"，则不会创建该作业。
dependency_scanning DEPENDENCY_SCANNING_DISABLED 如果值为 "true"，则不会创建该作业。
flawfinder-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
gemnasium-dependency_scanning DEPENDENCY_SCANNING_DISABLED 如果值为 "true"，则不会创建该作业。
gemnasium-maven-dependency_scanning DEPENDENCY_SCANNING_DISABLED 如果值为 "true"，则不会创建该作业。
gemnasium-python-dependency_scanning DEPENDENCY_SCANNING_DISABLED 如果值为 "true"，则不会创建该作业。
kubesec-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
license_management LICENSE_MANAGEMENT_DISABLED GitLab 12.7 及更早版本 如果存在该变量，则不会创建该作业。从 GitLab 12.8 开始已弃用。
license_scanning LICENSE_MANAGEMENT_DISABLED 如果值为 "true"，则不会创建该作业。从 GitLab 15.9 开始已弃用。
load_performance LOAD_PERFORMANCE_DISABLED 如果存在该变量，则不会创建该作业。
nodejs-scan-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
performance PERFORMANCE_DISABLED GitLab 13.12 及更早版本 浏览器性能。如果存在该变量，则不会创建该作业。被 browser_performance 替代。
browser_performance BROWSER_PERFORMANCE_DISABLED 浏览器性能。如果存在该变量，则不会创建该作业。替代 performance。
phpcs-security-audit-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
pmd-apex-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
review REVIEW_DISABLED 如果存在该变量，则不会创建该作业。
review:stop REVIEW_DISABLED 手动作业。如果存在该变量，则不会创建该作业。
secret_detection SECRET_DETECTION_DISABLED 如果值为 "true"，则不会创建该作业。
secret_detection_default_branch SECRET_DETECTION_DISABLED 如果值为 "true"，则不会创建该作业。
semgrep-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
sobelow-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
stop_dast_environment DAST_DISABLED_FOR_DEFAULT_BRANCH 或 DAST_DISABLED 如果值为 "true"，则不会创建该作业。
spotbugs-sast SAST_DISABLED 如果值为 "true"，则不会创建该作业。
test TEST_DISABLED 如果存在该变量，则不会创建该作业。
staging STAGING_ENABLED 如果存在该变量，则会创建该作业。
stop_review REVIEW_DISABLED 如果存在该变量，则不会创建该作业。

配置应用密钥变量

某些已部署的应用程序需要访问密钥变量。 Auto DevOps 检测以 K8S_SECRET_ 开头的 CI/CD 变量， 并将它们作为环境变量提供给已部署的应用程序。

先决条件：

  • 变量值必须是单行。

要配置密钥变量：

  1. 在左侧边栏，选择 Search or go to 并找到你的项目。
  2. 选择 Settings > CI/CD。
  3. 展开 Variables。
  4. 创建一个前缀为 K8S_SECRET_ 的 CI/CD 变量。例如，你可以创建一个名为 K8S_SECRET_RAILS_MASTER_KEY 的变量。
  5. 运行 Auto DevOps 管道，通过手动创建新管道或向 GitLab 推送代码更改。

Kubernetes 密钥

Auto DevOps 管道使用你的应用程序密钥变量来填充 Kubernetes 密钥。 此密钥在每个环境中都是唯一的。 部署你的应用程序时，密钥作为环境变量加载到运行应用程序的容器中。 例如，如果你创建一个名为 K8S_SECRET_RAILS_MASTER_KEY 的密钥，你的 Kubernetes 密钥可能如下所示：

$ kubectl get secret production-secret -n minimal-ruby-app-54 -o yaml

apiVersion: v1
data:
  RAILS_MASTER_KEY: MTIzNC10ZXN0
kind: Secret
metadata:
  creationTimestamp: 2018-12-20T01:48:26Z
  name: production-secret
  namespace: minimal-ruby-app-54
  resourceVersion: "429422"
  selfLink: /api/v1/namespaces/minimal-ruby-app-54/secrets/production-secret
  uid: 57ac2bfd-03f9-11e9-b812-42010a9400e4
type: Opaque

更新应用密钥

环境变量在 Kubernetes pod 中通常是不可变的。 如果你更新了应用程序密钥然后手动创建新管道，运行中的应用程序不会收到更新的密钥。

要更新应用程序密钥，可以：

  • 向 GitLab 推送代码更新以强制 Kubernetes 重新创建 pod。
  • 手动删除正在运行的 pod，以使 Kubernetes 创建带有更新密钥的新 pod。

由于 Auto DevOps 脚本环境的限制，不支持多行值的变量。

配置副本变量

当你想要扩展部署时，添加副本变量：

  1. 将副本变量添加为 项目 CI/CD 变量。

  2. 要扩展你的应用程序，重新部署它。

    不要直接使用 Kubernetes 扩展你的应用程序。Helm 可能无法检测到更改， 而后续的 Auto DevOps 部署可能会撤销你的更改。

自定义副本变量

你可以创建格式为 <TRACK>_<ENV>_REPLICAS 的自定义副本变量：

  • <TRACK> 是 Helm Chart 应用定义中设置的 track Kubernetes label 的全大写值。如果未设置 track，则从自定义变量中省略 <TRACK>。
  • <ENV> 是在 .gitlab-ci.yml 中设置的部署作业的全大写环境名称。

例如，如果环境是 qa 且 track 是 foo，创建一个名为 FOO_QA_REPLICAS 的环境变量：

QA testing:
  stage: deploy
  environment:
    name: qa
  script:
    - deploy foo

track foo 必须在应用程序的 Helm chart 中定义。例如：

replicaCount: 1
image:
  repository: gitlab.example.com/group/project
  tag: stable
  pullPolicy: Always
  secrets:
    - name: gitlab-registry
application:
  track: foo
  tier: web
service:
  enabled: true
  name: web
  type: ClusterIP
  url: http://my.host.com/
  externalPort: 5000
  internalPort: 5000

暂存和生产环境的部署策略

Auto DevOps 通常使用持续部署，并在默认分支上运行新管道时自动推送到 production 环境。 要手动部署到生产环境，你可以使用 STAGING_ENABLED CI/CD 变量。

如果你设置 STAGING_ENABLED，GitLab 会自动将应用程序部署到 staging 环境。 当你准备好部署到生产环境时，GitLab 会创建一个 production_manual 作业。

你也可以在 项目设置 中启用手动部署。

金丝雀环境的部署策略

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

你可以在将任何更改部署到生产环境之前使用 金丝雀环境。

如果你设置 CANARY_ENABLED，GitLab 会创建两个 手动作业：

  • canary - 将应用程序部署到金丝雀环境。
  • production_manual - 将应用程序部署到生产环境。

生产环境的逐步部署

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用逐步部署来持续部署你的应用程序，从少数几个 pod 开始。你可以手动增加 pod 的数量。

你可以在 项目设置 中启用手动部署， 或将 INCREMENTAL_ROLLOUT_MODE 设置为 manual。

如果你将 INCREMENTAL_ROLLOUT_MODE 设置为 manual，GitLab 会创建四个手动作业：

  1. rollout 10%
  2. rollout 25%
  3. rollout 50%
  4. rollout 100%

百分比基于 REPLICAS CI/CD 变量，定义了用于部署的 pod 数量。 例如，如果值为 10 且你运行 10% 的部署作业，你的应用程序只会部署到一个 pod。

你可以按任何顺序运行部署作业。要缩减规模，重新运行较低百分比的作业。

运行 rollout 100% 作业后，你不能缩减规模，必须 回滚你的部署。

逐步部署配置示例

没有 INCREMENTAL_ROLLOUT_MODE 且没有 STAGING_ENABLED：

CI/CD workflow visualization graph with both incremental rollout and staging disabled

没有 INCREMENTAL_ROLLOUT_MODE 且有 STAGING_ENABLED：

CI/CD workflow visualization graph with incremental rollout disabled and staging enabled

有 INCREMENTAL_ROLLOUT_MODE 设置为 manual 且没有 STAGING_ENABLED：

CI/CD workflow visualization graph with incremental rollout enabled and staging disabled

有 INCREMENTAL_ROLLOUT_MODE 设置为 manual 且有 STAGING_ENABLED：

CI/CD workflow visualization graph with both incremental rollout and staging enabled

生产环境的定时逐步部署

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用定时逐步部署来持续部署你的应用程序，从少数几个 pod 开始。

你可以在 项目设置 中启用定时逐步部署， 或将 INCREMENTAL_ROLLOUT_MODE CI/CD 变量设置为 timed。

如果你将 INCREMENTAL_ROLLOUT_MODE 设置为 timed，GitLab 会创建四个作业：

  1. timed rollout 10%
  2. timed rollout 25%
  3. timed rollout 50%
  4. timed rollout 100%

作业之间有五分钟的延迟。