极狐 GitLab

极狐GitLab Runner 功能标志

如果您启用默认禁用的功能，可能会出现数据损坏、稳定性下降、性能下降和安全问题。在启用功能标志之前，您应了解相关风险。有关更多信息，请参阅启用仍在开发中的功能时的风险。

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

  • 供志愿者测试、但尚未准备好面向所有用户启用的测试版功能。

    测试版功能有时并不完整，或需要进一步测试。想要使用测试版功能的用户 可以选择接受风险，并通过功能标志显式启用该功能。其他不需要该功能， 或不愿在自己的系统上承担风险的用户，该功能默认处于禁用状态， 不会受到可能的缺陷和回归的影响。

  • 会导致功能弃用或近期移除的破坏性变更。

    随着产品演进，功能有时会被更改或完全移除。已知缺陷通常会得到修复， 但在某些情况下，用户已经针对影响自己的缺陷找到了变通方法；强制用户 采用标准化的缺陷修复，可能会给其自定义配置带来其他问题。

    在这种情况下，功能标志用于按需从旧行为切换到新行为。这样， 用户可以采用新版本的产品，同时有时间规划从旧行为到新行为的 平稳、永久过渡。

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

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

可用的功能标志#

功能标志默认值已弃用移除版本描述
FF_NETWORK_PER_BUILDfalse 否使用 docker 执行器时，为每次构建创建一个 Docker 网络。使用 CI_BUILD_NETWORK_NAME 变量获取网络名称。
FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGYfalse 否设置为 false 时，禁用通过 exec 执行远程 Kubernetes 命令，改用 attach，以解决诸如 #4119 之类的问题。此功能标志要求服务账号具有特定权限。有关更多信息，请参阅配置 runner API 权限。
FF_USE_DIRECT_DOWNLOADtrue 否设置为 true 时，Runner 在首次尝试下载产物时发送 direct_download=true 和 download_mode=direct。这会请求极狐GitLab 将产物下载重定向到对象存储（例如 S3），而不是通过极狐GitLab 代理传输产物字节。仅当管理员允许时，极狐GitLab 才会采用直接模式；否则，极狐GitLab 使用配置的 proxy_download 模式。重试时，Runner 会省略这两个参数，并使用配置的下载模式。如果网络错误导致重试，且启用了 proxy_download，极狐GitLab 可以代理该重试。HTTP 401 和 403 响应不会重试。如果 Runner 无法验证对象存储的 TLS 证书，直接下载可能会失败。请参阅允许客户端覆盖代理下载和自签名证书或自定义证书颁发机构。
FF_USE_FASTZIPtrue 是19.7Fastzip 是用于缓存/产物归档和解压的高性能归档工具。默认启用。设置为 false 可使用旧版 zip 实现。已弃用：旧版 zip 实现和此标志将在极狐GitLab Runner 19.7 中移除，此后将始终使用 fastzip。
FF_DISABLE_UMASK_FOR_DOCKER_EXECUTORfalse 否启用后，对于使用 docker 执行器执行的作业，不再使用 umask 0000 调用。取而代之的是，runner 会查找为构建容器镜像配置的用户的 UID 和 GID。然后，runner 通过在预定义容器中运行 chmod 命令（在更新源代码、恢复缓存和下载产物之后）来更改构建目录及其文件的所有权。当构建目录位于（可能共享的）挂载卷上时，只会更改检出文件和临时文件的所有权。构建镜像中必须安装并可使用 POSIX 工具 id。runner 使用 -u 和 -g 选项运行 id 以获取 UID 和 GID。
FF_ENABLE_BASH_EXIT_CODE_CHECKfalse 否如果启用，bash 脚本不会仅依赖 set -e，而是在每条脚本命令执行后检查非零退出码。
FF_USE_WINDOWS_LEGACY_PROCESS_STRATEGYfalse 是19.8在极狐GitLab Runner 16.10 及更高版本中，默认值为 false。在极狐GitLab Runner 16.9 及更早版本中，默认值为 true。禁用时，Runner 在 Windows 上创建的进程（shell 和自定义执行器）将使用额外的设置创建，这应能改善进程终止。设置为 true 时，使用旧版进程设置。要成功且优雅地排空 Windows Runner，应将此功能标志设置为 false。已弃用：旧版进程设置和此标志将在极狐GitLab Runner 19.8 中移除，此后将始终使用当前进程设置。
FF_USE_LEGACY_BASH_EVALfalse 否设置为 true 时，Bash eval 调用使用旧版流水线调用形式。默认值（false）将 eval 包装在带陷阱的子 shell 中，以防止在 Bash 4.4 之前的版本以及 Bash 5.3 及更高版本中取消时脚本主体泄漏。有关更多信息，请参阅议题 39005。如果默认行为导致问题，请使用此标志。
FF_USE_POWERSHELL_PATH_RESOLVERfalse 否启用后，由 PowerShell 解析路径名，而不是由 Runner 使用特定于 Runner 所在主机的操作系统文件路径函数。
FF_USE_DYNAMIC_TRACE_FORCE_SEND_INTERVALfalse 否启用后，日志的跟踪强制发送间隔会根据跟踪更新间隔动态调整。
FF_SCRIPT_SECTIONSfalse 否启用后，多行脚本命令在作业日志中显示为可折叠的区块，而单行命令则直接以 $ 前缀打印。这是一个已知问题。有关更多信息，请参阅议题 39294。
FF_ENABLE_JOB_CLEANUPfalse 否启用后，项目目录将在构建结束时清理。如果使用 GIT_CLONE，整个项目目录将被删除。如果使用 GIT_FETCH，将执行一系列 Git clean 命令。
FF_KUBERNETES_HONOR_ENTRYPOINTfalse 否启用后，如果 FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY 未设置为 true，将遵循镜像的 Docker 入口点。此功能标志要求服务账号具有特定权限。有关更多信息，请参阅配置 runner API 权限。
FF_POSIXLY_CORRECT_ESCAPESfalse 否启用后，使用 POSIX shell 转义，而不是 bash 风格的 ANSI-C 引用。如果作业环境使用符合 POSIX 的 shell，则应启用此标志。
FF_RESOLVE_FULL_TLS_CHAINfalse 是20.0在极狐GitLab Runner 16.4 及更高版本中，默认值为 false。在极狐GitLab Runner 16.3 及更早版本中，默认值为 true。启用后，runner 会为 CI_SERVER_TLS_CA_FILE 解析完整的 TLS 链，一直追溯到自签名根证书。对于使用 v7.68.0 之前的 libcurl 和 OpenSSL 构建的 Git 客户端，此前需要这样做才能使 Git HTTPS 克隆正常工作。但是，在某些操作系统（例如 macOS）上，解析证书的过程可能会失败，因为这些系统会拒绝使用较旧签名算法签名的根证书。如果证书解析失败，您可能需要禁用此功能。此功能标志只能在 [runners.feature_flags] 配置中禁用。已弃用：完整 TLS 链解析和此标志将在极狐GitLab Runner 20.0 中移除。需要已解析证书链的客户端必须直接通过 CI_SERVER_TLS_CA_FILE 提供。
FF_DISABLE_POWERSHELL_STDINfalse 否启用后，shell 和自定义执行器的 PowerShell 脚本通过文件传递，而不是通过 stdin 传递和执行。这是作业的 allow_failure:exit_codes 关键字正常工作的必要条件。
FF_USE_POD_ACTIVE_DEADLINE_SECONDStrue 否启用后，Pod 的 activeDeadlineSeconds 设置为 CI/CD 作业超时。此标志会影响 Pod 的生命周期。
FF_USE_ADVANCED_POD_SPEC_CONFIGURATIONfalse 否启用后，用户可以在 config.toml 文件中设置完整的 Pod 规范。有关更多信息，请参阅覆盖生成的 Pod 规范（实验）。
FF_SECRET_RESOLVING_FAILS_IF_MISSINGtrue 否启用后，如果找不到值，密钥解析将失败。
FF_PRINT_POD_EVENTSfalse 否启用后，将打印与构建 Pod 关联的所有事件，直到该 Pod 启动。
FF_USE_GIT_BUNDLE_URIStrue 否启用后，Git transfer.bundleURI 配置选项设置为 true。此功能标志默认启用。设置为 false 可禁用 Git bundle 支持。
FF_USE_GIT_NATIVE_CLONEfalse 否启用且 GIT_STRATEGY=clone 时，使用 git-clone(1) 命令克隆项目，而不是 git-init(1) + git-fetch(1)。这需要 Git 2.49 及更高版本，如果不可用，则回退到 init + fetch。
FF_USE_DUMB_INIT_WITH_KUBERNETES_EXECUTORfalse 否启用后，使用 dumb-init 执行所有脚本。这允许 dumb-init 作为辅助容器和构建容器中的第一个进程运行。
FF_USE_INIT_WITH_DOCKER_EXECUTORfalse 否启用后，Docker 执行器使用 --init 选项启动服务和构建容器，该选项会将 tini-init 作为 PID 1 运行。
FF_LOG_IMAGES_CONFIGURED_FOR_JOBfalse 否启用后，runner 会记录为每个收到的作业定义的镜像和服务镜像的名称。
FF_USE_DOCKER_AUTOSCALER_DIAL_STDIOtrue 否启用后（默认），使用 docker system stdio 建立到远程 Docker 守护进程的隧道。禁用后，对于 SSH 连接使用原生 SSH 隧道，对于 WinRM 连接则先部署一个 'fleeting-proxy' 辅助二进制文件。
FF_CLEAN_UP_FAILED_CACHE_EXTRACTfalse 否启用后，会将命令插入构建脚本，以检测失败的缓存提取并清理遗留的部分缓存内容。
FF_USE_WINDOWS_JOB_OBJECTfalse 否启用后，会为 runner 在 Windows 上使用 shell 和自定义执行器创建的每个进程创建一个作业对象。为强制终止进程，runner 会关闭该作业对象。这应能改善难以终止的进程的终止情况。
FF_TIMESTAMPStrue 否禁用后，不会在每行日志跟踪记录的开头添加时间戳。
FF_DISABLE_AUTOMATIC_TOKEN_ROTATIONfalse 否启用后，会限制自动令牌轮换，并在令牌即将过期时记录警告。
FF_USE_LEGACY_GCS_CACHE_ADAPTERfalse 否启用后，使用旧版 GCS 缓存适配器。禁用后（默认），使用较新的 GCS 缓存适配器，它使用 Google Cloud Storage 的 SDK 进行身份验证。这应能解决旧版适配器难以处理的环境中的身份验证问题，例如 GKE 中的工作负载身份配置。
FF_DISABLE_UMASK_FOR_KUBERNETES_EXECUTORfalse 否启用后，对于使用 Kubernetes 执行器执行的作业，不再使用 umask 0000 调用。取而代之的是，runner 会尝试查找构建容器所运行用户的用户 ID (UID) 和组 ID (GID)。runner 还会通过在预定义容器中运行 chown 命令（在更新源代码、恢复缓存和下载产物之后）来更改工作目录和文件的所有权。
FF_USE_LEGACY_S3_CACHE_ADAPTERfalse 否启用后，使用旧版 S3 缓存适配器。禁用后（默认），使用较新的 S3 缓存适配器，它使用 Amazon 的 S3 SDK 进行身份验证。这应能解决旧版适配器难以处理的环境中的身份验证问题，例如自定义 STS 端点。
FF_GIT_URLS_WITHOUT_TOKENSfalse 否启用后，极狐GitLab Runner 在 Git 配置或命令执行期间不会在任何位置嵌入作业令牌。取而代之的是，它会设置一个 Git 凭据助手，使用环境变量获取作业令牌。这种方法限制了令牌的存储，降低了令牌泄漏的风险。
FF_WAIT_FOR_POD_TO_BE_REACHABLEfalse 否启用后，runner 会等待 Pod 状态变为 'Running'，并等待 Pod 就绪且已附加证书。有关更多信息，请参阅配置 runner API 权限。
FF_MASK_ALL_DEFAULT_TOKENStrue 否启用后，极狐GitLab Runner 会自动遮盖所有默认令牌模式。
FF_EXPORT_HIGH_CARDINALITY_METRICSfalse 否启用后，runner 会导出高基数指标。启用此功能标志时应特别小心，以避免摄取大量数据。有关更多信息，请参阅 Runner 集群扩缩。
FF_USE_FLEETING_ACQUIRE_HEARTBEATSfalse 否启用后，在将作业分配给实例之前会检查 fleeting 实例的连通性。
FF_USE_EXPONENTIAL_BACKOFF_STAGE_RETRYtrue 否启用后，GET_SOURCES_ATTEMPTS、ARTIFACT_DOWNLOAD_ATTEMPTS、RESTORE_CACHE_ATTEMPTS、EXECUTOR_JOB_SECTION_ATTEMPTS 和 SECRETS_RETRIEVAL_ATTEMPTS的重试使用指数退避（5 秒 - 5 分钟）。
FF_USE_ADAPTIVE_REQUEST_CONCURRENCYtrue 否启用后，request_concurrency 设置将成为最大并发值，并发请求数会根据成功作业请求的速率进行调整。
FF_USE_GITALY_CORRELATION_IDtrue 否启用后，X-Gitaly-Correlation-ID 请求头会添加到所有 Git HTTP 请求中。禁用后，Git 操作执行时不带 Gitaly 关联 ID 请求头。
FF_USE_GIT_PROACTIVE_AUTHfalse 否启用后，runner 会将 http.proactiveAuth=basic Git 配置选项传递给 git clone 和 git fetch 命令。因此，Git 会主动发送凭据，而不是等待 401 响应。此行为可确保用户名传播到 Gitaly，以用于公开项目。
FF_HASH_CACHE_KEYSfalse 否当极狐GitLab Runner 创建或提取缓存时，会在使用缓存键之前对其进行哈希（SHA256），本地缓存和分布式缓存（例如 S3）均如此。有关更多信息，请参阅缓存键处理。
FF_ENABLE_JOB_INPUTS_INTERPOLATIONtrue 否启用后，作业输入会被插值。有关更多信息，请参阅 &17833。
FF_USE_JOB_ROUTERfalse 否使极狐GitLab Runner 通过连接到 Job Router 而不是直接连接极狐GitLab 来获取作业。
FF_SCRIPT_TO_STEP_MIGRATIONfalse 否启用后，用户脚本会迁移为步骤，并使用 step-runner 执行。
FF_USE_PARALLEL_CACHE_TRANSFERfalse 否启用后，缓存上传和下载使用并行对象存储传输：GoCloud 写入使用带并发分片的多部分上传；下载使用并发 HTTP Range 或 GoCloud 范围读取。禁用后，上传使用单个并发分片流，下载使用单个流。启用后可提高高带宽链路的吞吐量。可使用 CACHE_CONCURRENCY 和 CACHE_CHUNK_SIZE 进行调整。
FF_USE_PARALLEL_ARTIFACT_TRANSFERfalse 否启用后，使用 direct_download 并收到对象存储重定向的产物下载，在后端支持带 Content-Range 总量的 206 Partial Content 时，可以使用并行 HTTP Range GET。禁用后，使用单个下载流。分块大小和并发数在 runner 中是固定的（不是 CACHE_* 变量）。
FF_CONCRETEfalse 否启用后，传统脚本执行会迁移为使用 step-runner 执行。
FF_SUSPENDABLE_ENVIRONMENTSfalse 否启用后，您可以挂起或恢复作业环境。
FF_USE_NATIVE_CONTAINER_STOPfalse 否启用后，使用容器引擎的原生关闭机制在作业取消时终止构建容器。SIGTERM 仅传递给 PID 1。PID 1 必须优雅且正确地终止进程树的其余部分。仅当已知 PID 1 能处理 SIGTERM 并将关闭信号传播给其后代进程（例如转发信号的 init 进程，或设计为协调自身拆除的应用程序）时，才启用此标志。禁用后（默认），runner 会应用自己的优雅终止机制，直接向子进程发送信号。当进程树包含 shell 或其他不会将 SIGTERM 传播给其子进程的进程时，直接发送信号是必要的。
FF_MACHINE_OPTIONS_EXPAND_ENVfalse 否启用后，在创建机器时，[runners.machine] 部分的 MachineOptions 和 MachineOptionsWithName中的 $VAR 和 ${VAR} 引用会替换为 runner 环境中的值。${GITLAB_RUNNER_MACHINE_NAME} 是正在创建的机器的名称，它会替换 MachineOptionsWithName。
FF_DOCKER_MACHINE_JSON_OUTPUTfalse 否启用后，docker-machine create 会以 --log-format=json 运行（需要 Docker Machine 0.16.2-gitlab.55 或更高版本）。runner 会将 Docker Machine 的字段作为结构化字段记录在 docker_machine 下，并在 gitlab_runner_autoscaling_machine_creation_phase_duration_seconds中记录每个阶段的创建耗时。

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

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

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

    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.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.com/"
4  token = "TOKEN"
5  executor = "docker"
6  [runners.feature_flags]
7    FF_USE_DIRECT_DOWNLOAD = true