极狐 GitLab Logo

极狐GitLab Runner 功能标志

如果你启用了一个未默认启用的功能，可能会发生数据丢失、稳定性降级以及安全问题。在你启用功能标志前，你应该了解涉及的风险。更多信息，请参见启用仍在开发中的功能的风险。

功能标志#

功能标志是允许您启用或禁用特定功能的开关。这些标志通常用于：

  • 为了让志愿者测试的测试版功能，但尚未准备好为所有用户启用。

    测试版功能有时不完整或需要进一步测试。想要使用测试版功能的用户可以选择接受风险并通过功能标志明确启用该功能。其他不需要该功能或不愿意在其系统上承担风险的用户默认情况下禁用该功能，不受可能的错误和回归的影响。

  • 对未来导致功能废弃或移除的重大更改。

    随着产品的发展，功能有时会被更改或完全移除。已知错误通常会被修复，但在某些情况下，用户已经找到了影响他们的错误的解决方法；强迫用户采用标准化的错误修复可能会导致他们的自定义配置出现其他问题。

    在这种情况下，功能标志用于按需从旧行为切换到新行为。这允许用户采用产品的新版本，同时给他们时间计划从旧行为到新行为的平稳、永久过渡。

功能标志通过环境变量进行切换。要：

  • 激活功能标志，设置对应的环境变量为 "true" 或 1。
  • 取消激活功能标志，设置对应的环境变量为 "false" 或 0。

可用功能标志#

功能标志默认值已弃用将在以下版本中移除描述
FF_NETWORK_PER_BUILDfalse No在使用 docker 执行器时启用为每个构建创建一个 Docker 网络
FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGYfalse No设置为 false 时禁用通过 exec 执行远程 Kubernetes 命令，转而使用 attach 来解决问题。
FF_USE_DIRECT_DOWNLOADtrue No设置为 true 时，Runner 尝试直接下载所有产物，而不是首先通过极狐GitLab 代理。启用可能会导致下载失败，因为极狐GitLab 启用了对象存储的 TLS 证书验证问题。请参阅 自签名证书或自定义认证机构
FF_SKIP_NOOP_BUILD_STAGEStrue No设置为 false 时，即使运行它们没有效果，所有构建阶段也会被执行
FF_USE_FASTZIPfalse NoFastzip 是用于缓存/产物归档和提取的高性能归档器
FF_DISABLE_UMASK_FOR_DOCKER_EXECUTORfalse No如果启用，将移除对使用 docker 执行器执行的作业的 umask 0000 调用。相反，Runner 将尝试发现为构建容器使用的镜像配置的用户的 UID 和 GID，并通过在预定义容器中运行 chmod 命令来更改工作目录和文件的所有权（在更新源、恢复缓存和下载产物之后）。POSIX 实用程序 id 必须安装并在构建镜像中运行才能使用此功能标志。Runner 将使用选项 -u 和 -g 执行 id 以检索 UID 和 GID。
FF_ENABLE_BASH_EXIT_CODE_CHECKfalse No如果启用，bash 脚本不仅依赖于 set -e，而是在执行每个脚本命令后检查非零退出代码。
FF_USE_WINDOWS_LEGACY_PROCESS_STRATEGYfalse No在极狐GitLab Runner 16.10 及更高版本中，默认值为 false。在极狐GitLab Runner 16.9 及更早版本中，默认值为 true。禁用时，Runner 在 Windows 上创建的进程（shell 和自定义执行器）将使用额外的设置来改进进程终止。设置为 true 时，将使用传统进程设置。要成功并优雅地排空 Windows Runner，应将此功能标志设置为 false。
FF_USE_NEW_BASH_EVAL_STRATEGYfalse No设置为 true 时，Bash eval 调用在子 shell 中执行，以帮助正确检测执行的脚本的退出代码。
FF_USE_POWERSHELL_PATH_RESOLVERfalse No启用时，PowerShell 解析路径名，而不是 Runner 使用特定于 Runner 托管位置的操作系统特定文件路径功能。
FF_USE_DYNAMIC_TRACE_FORCE_SEND_INTERVALfalse No启用时，日志的跟踪强制发送间隔会根据跟踪更新间隔动态调整。
FF_SCRIPT_SECTIONSfalse No启用时，来自 .gitlab-ci.yml 文件的每个脚本行都在作业输出中为可折叠部分，并显示每行的持续时间。当命令跨多行时，完整命令会显示在作业日志输出终端中。
FF_ENABLE_JOB_CLEANUPfalse No启用时，项目目录将在构建结束时清理。如果使用 GIT_CLONE，整个项目目录将被删除。如果使用 GIT_FETCH，将发出一系列 Git clean 命令。
FF_KUBERNETES_HONOR_ENTRYPOINTfalse No启用时，如果未设置 FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY 为 true，将遵循镜像的 Docker entrypoint
FF_POSIXLY_CORRECT_ESCAPESfalse No启用时，将使用 POSIX shell 转义，而不是 bash 风格的 ANSI-C 引用。如果作业环境使用 POSIX 兼容的 shell，应该启用这个选项。
FF_RESOLVE_FULL_TLS_CHAINfalse No在极狐GitLab Runner 16.4 及更高版本中，默认值为 false。在极狐GitLab Runner 16.3 及更早版本中，默认值为 true。启用时，Runner 会解析完整的 TLS 链，直到 CI_SERVER_TLS_CA_FILE 的自签名根证书。这之前是 需要的，以使 Git HTTPS 克隆工作，适用于使用 libcurl v7.68.0 之前版本和 OpenSSL 构建的 Git 客户端。但是，解析证书的过程可能会在某些操作系统上失败，例如 macOS，它们拒绝使用较旧签名算法签署的根证书。如果证书解析失败，您可能需要禁用此功能。此功能标志只能在 [runners.feature_flags] 配置中禁用。
FF_DISABLE_POWERSHELL_STDINfalse No启用时，shell 和自定义执行器的 PowerShell 脚本通过文件传递，而不是通过 stdin 传递和执行。这是为了使作业的 allow_failure:exit_codes 关键字正常工作。
FF_USE_POD_ACTIVE_DEADLINE_SECONDStrue No启用时，pod activeDeadlineSeconds 被设置为 CI/CD 作业超时。此标志会影响 pod 的生命周期。
FF_USE_ADVANCED_POD_SPEC_CONFIGURATIONfalse No启用时，用户可以在 config.toml 文件中设置整个 pod 规范。有关详细信息，请参阅 覆盖生成的 pod 规范（实验）。
FF_SET_PERMISSIONS_BEFORE_CLEANUPtrue No启用时，首先设置项目目录中目录和文件的权限，以确保在清理期间删除成功。
FF_SECRET_RESOLVING_FAILS_IF_MISSINGtrue No启用时，如果找不到值，密钥解析将失败。
FF_RETRIEVE_POD_WARNING_EVENTStrue Yes启用时，当作业失败时，将检索与 pod 相关的所有警告事件。此标志在极狐GitLab Runner 17.2 中已弃用，并计划在 18.0 中移除。在极狐GitLab Runner 17.2 及更高版本中，pod 警告事件将被无条件检索和记录。但是，即使缺少 RBAC 权限，也不会发生故障。
FF_PRINT_POD_EVENTSfalse No启用时，在构建 pod 启动之前，将打印与其相关的所有事件。
FF_USE_GIT_BUNDLE_URIStrue No启用时，Git transfer.bundleURI 配置选项设置为 true。此 FF 默认启用。设置为 false 以禁用 Git 捆绑支持。
FF_USE_DUMB_INIT_WITH_KUBERNETES_EXECUTORfalse No启用时，dumb-init 用于执行所有脚本。这允许 dumb-init 作为第一个进程运行在辅助和构建容器中。
FF_USE_INIT_WITH_DOCKER_EXECUTORfalse No启用时，Docker 执行器使用 --init 选项启动服务和构建容器，该选项将 tini-init 作为 PID 1 运行。
FF_LOG_IMAGES_CONFIGURED_FOR_JOBfalse No启用时，runner 会记录为每个接收的作业定义的镜像和服务镜像的名称。
FF_USE_DOCKER_AUTOSCALER_DIAL_STDIOtrue No启用时（默认），docker system stdio 用于隧道到远程 Docker 守护程序。禁用时，对于 SSH 连接，使用本机 SSH 隧道；对于 WinRM 连接，则首先部署 'fleeting-proxy' 辅助二进制文件。
FF_CLEAN_UP_FAILED_CACHE_EXTRACTfalse No启用时，将命令插入到构建脚本中以检测失败的缓存提取并清理留下的部分缓存内容。
FF_USE_WINDOWS_JOB_OBJECTfalse No启用时，为 Runner 在 Windows 上使用 shell 和自定义执行器创建的每个进程创建一个作业对象。要强制终止进程，Runner 会关闭作业对象。这应该改进难以终止的进程的终止。
FF_TIMESTAMPSfalse No启用时，在每个日志跟踪行的开头添加时间戳。
FF_DISABLE_AUTOMATIC_TOKEN_ROTATIONfalse No启用时，它限制自动令牌轮换，并在令牌即将过期时记录警告。
FF_USE_LEGACY_GCS_CACHE_ADAPTERfalse No启用时，使用传统的 GCS 缓存适配器。禁用时（默认），使用更新的 GCS 缓存适配器，该适配器使用 Google Cloud Storage 的 SDK 进行身份验证。这应该可以解决在传统适配器困难的环境中（例如 GKE 中的工作负载身份配置）身份验证问题。
FF_DISABLE_UMASK_FOR_KUBERNETES_EXECUTORfalse No启用时，移除对使用 Kubernetes 执行器执行的作业的 umask 0000 调用。相反，runner 会尝试发现构建容器运行的用户的用户 ID (UID) 和组 ID (GID)。runner 还通过在预定义容器中运行 chown 命令更改工作目录和文件的所有权（在更新源、恢复缓存和下载产物之后）。
FF_USE_LEGACY_S3_CACHE_ADAPTERfalse No启用时，使用传统的 S3 缓存适配器。禁用时（默认），使用更新的 S3 缓存适配器，该适配器使用亚马逊的 S3 SDK 进行身份验证。这应该可以解决在传统适配器困难的环境中（例如自定义 STS 端点）身份验证问题。
FF_GIT_URLS_WITHOUT_TOKENSfalse No启用时，极狐GitLab Runner 在 Git 配置或命令执行期间不会在任何地方嵌入作业令牌。相反，它设置了一个 Git 凭证助手，该助手使用环境变量获取作业令牌。这种方法限制了令牌存储，并减少了泄漏的可能性。
FF_WAIT_FOR_POD_TO_BE_REACHABLEfalse No启用时，runner 会等待 Pod 状态为 'Running'，并且 Pod 已准备好并附加了其证书。
FF_USE_NATIVE_STEPStrue No启用时，并且当作业使用 'run' 关键字指定时，步骤通过 原生步骤 Runner 集成 执行。这仅适用于支持本机步骤集成的执行器，如 Docker、Docker Autoscaler、Docker for Windows。
FF_MASK_ALL_DEFAULT_TOKENStrue No启用时，极狐GitLab Runner 会自动屏蔽所有默认令牌模式。
FF_EXPORT_HIGH_CARDINALITY_METRICSfalse No启用时，runner 会导出具有高基数的指标。在启用此功能标志时应特别注意，以避免摄取大量数据。有关更多信息，请参阅 Fleet scaling。
FF_USE_FLEETING_ACQUIRE_HEARTBEATSfalse No启用时，在将作业分配给实例之前，会检查短暂实例的连接性。

在流水线配置中启用功能标志#

您可以使用 CI 变量 启用功能标志：

  • 对流水线中的所有作业（全局）：

    yaml
    variables:
  FEATURE_FLAG_NAME: 1

  • 针对单个作业：

    yaml
    1job:
2  stage: test
3  variables:
4    FEATURE_FLAG_NAME: 1
5  script:
6  - echo "Hello"

在 runner 环境变量中启用功能标志#

要为 Runner 运行的每个作业启用该功能，请将功能标志指定为 Runner 配置中的 environment 变量：

toml
1[[runners]]
2  name = "example-runner"
3  url = "https://gitlab.example.com/"
4  token = "TOKEN"
5  limit = 0
6  executor = "docker"
7  builds_dir = ""
8  shell = ""
9  environment = ["FEATURE_FLAG_NAME=1"]

在 runner 配置中启用功能标志#

您可以通过在 [runners.feature_flags] 下指定功能标志来启用它们。此设置可防止任何作业覆盖功能标志值。

某些功能标志也只能在您配置此设置时使用，因为它们不涉及作业如何执行。

toml
1[[runners]]
2  name = "example-runner"
3  url = "https://gitlab.example.com/"
4  token = "TOKEN"
5  executor = "docker"
6  [runners.feature_flags]
7    FF_USE_DIRECT_DOWNLOAD = true