极狐GitLab Runner 功能标志

如果您启用了默认被禁用的功能，可能会发生数据损坏、稳定性降低、性能降低和安全问题。在启用功能标志之前，您应该了解其中涉及的风险。更多信息，请参见启用仍在开发中的功能的风险。

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

还未准备好向所有用户开放的用于测试的 beta 功能。

Beta 功能有时不完整或需要进一步测试。想要使用 beta 功能的用户可以选择接受风险并明确开启带有功能标志的功能。对于其他不需要这个功能或不愿意接受风险的用户，这个功能默认禁用，且不受可能的错误或回退的影响。
对于涉及到近期内功能弃用或移除的大改变。

随着产品的演进，有些功能会发生改变或完全移除。已知错误会被修复，但在一些情况下，用户已经找到了影响其错误的解决方法，强制用户以标准化的方法修复错误可能会导致其他自定义配置的问题。

在这种情况下，功能标签被用于按需从旧行为向新行为切换。这种做法允许用户使用新版本的产品，但同时给予他们平缓持续地从旧行为向新行为切换的时间。

使用环境变量可以控制功能标记。用于：

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

可用功能标志

功能标志	默认值	废弃	描述
`FF_CMD_DISABLE_DELAYED_ERROR_LEVEL_EXPANSION`	`false`	否	使用 Window Batch Shell 时，为错误检查禁用启用延迟扩展。
`FF_NETWORK_PER_BUILD`	`false`	否	用 `docker` 执行器启用 Docker 每个构建的网络的创建。
`FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY`	`false`	否	设置为 `false` 时，会禁用远端 Kubernetes 命令通过 `exec` 的执行，代而使用 `attach`。
`FF_USE_DIRECT_DOWNLOAD`	`true`	否	当设置为 `true`，Runner 试图直接下载所有产物，而不是在第一次尝试时通过极狐GitLab 进行代理。如果由极狐GitLab 开启，可能会导致由验证对象存储的 TLS 证书问题而引发下载失败。详情请参见自签名证书或自定义证书授权。
`FF_SKIP_NOOP_BUILD_STAGES`	`true`	否	当设置为 `false`，即使运行没有效果，也会执行所有构建阶段。
`FF_USE_FASTZIP`	`false`	否	Fastzip 是缓存/产物归档和提取的归档。
`FF_DISABLE_UMASK_FOR_DOCKER_EXECUTOR`	`false`	否	如果启用，会移除对用 `docker` 执行器执行的作业的 `umask 0000` 调用。Runner 会试图发现构建容器所使用的镜像所配置的用户 UID 和 GID，并且会在预定义的容器（在更新源、恢复缓存和下载产物后）中通过运行 `chmod` 命令，更改工作目录的所有权。必须安装 POSIX utility `id` ，且它必须在这个功能标志的构建镜像中可运转。Runner 会使用 `-u` 和 `-g` 选项执行 `id`，用以检索 UID 和 GID。
`FF_ENABLE_BASH_EXIT_CODE_CHECK`	`false`	否	如果启用，bash 脚本不仅依赖于 `set -e`，但是在执行每个脚本命令后会检查非零退出码。
`FF_USE_WINDOWS_LEGACY_PROCESS_STRATEGY`	`true`	否	如果禁用，Runner 会使用额外设置在 Windows（Shell 和自定义执行器）上创建进程，这些设置应该改进进程终止。目前处于实验阶段，我们设置进程的方式会持续改进。当设置为 `true`，会使用遗留进程设置。为了成功且优雅地耗尽 Windows Runner, 这个功能标志应该被设置为 `false`。
`FF_USE_NEW_BASH_EVAL_STRATEGY`	`false`	否	当设置为 `true`，会在子壳上执行 Bash `eval` 调用，以帮助执行脚本的合理退出码检测。
`FF_USE_POWERSHELL_PATH_RESOLVER`	`false`	否	如果启用，PowerShell 使用托管 Runner 的特定 OS 的文件路径功能去解析路径名，而不是 Runner。
`FF_USE_DYNAMIC_TRACE_FORCE_SEND_INTERVAL`	`false`	否	如果启用，日志的跟踪强制发送间隔基于跟踪更新间隔进行动态调整。
`FF_SCRIPT_SECTIONS`	`false`	否	如果启用，来自 `.gitlab-ci.yml` 文件的每个脚本行会在作业输出的可折叠部分，并且展示每行的持续时间。
`FF_USE_NEW_SHELL_ESCAPE`	`false`	否	如果启用，使用 Shell 逃跑的快速执行。
`FF_ENABLE_JOB_CLEANUP`	`false`	否	如果启用，在构建结尾会清理项目目录。如果使用了 `GIT_CLONE`，整个项目目录会被删除。如果使用了 `GIT_FETCH`，会发行一系列 Git `clean` 命令。
`FF_KUBERNETES_HONOR_ENTRYPOINT`	`false`	否	如果启用，且 `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY` 没被设置为”true”，镜像的 Docker 入口点将会被 honored。
`FF_POSIXLY_CORRECT_ESCAPES`	`false`	否	如果启用，会使用 POSIX Shell 逃跑，而不是 `bash`-style ANSI-C quoting。如果作业环境使用了符合 POSIX 的 Shell，它应该被启用。
`FF_USE_IMPROVED_URL_MASKING`	`false`	否	如果启用，不论在跟踪日志输出的哪里出现，任何敏感 URL 参数都会被隐藏。这个功能标志只能通过 Runner 的配置而不是作业进行配置。
`FF_RESOLVE_FULL_TLS_CHAIN`	`true`	否	启用后，Runner 会解析完整的 TLS 链，一直解析到 `CI_SERVER_TLS_CA_FILE` 的自签名根证书。对于使用 v7.68.0 之前的 libcurl 和 OpenSSL 构建的 Git 客户端来说，这以前是 Git HTTPS 克隆工作的必需条件。但是，在某些操作系统（例如 macOS）上解析证书可能会失败，这些操作系统拒绝使用较旧的签名算法签署的根证书。如果证书解析失败，您可能需要禁用此功能。此功能标志只能在 `[runners.feature_flags]` 配置中禁用。
`FF_DISABLE_POWERSHELL_STDIN`	`false`	否	启用后，Shell 和自定义执行器的 PowerShell 脚本将通过文件传递，而不是通过标准输入传递和执行。
`FF_USE_POD_ACTIVE_DEADLINE_SECONDS`	`false`	否	启用后，pod `activeDeadlineSeconds` 会被设置为 CI/CD 作业超时时间。这个标志影响 pod 的生命周期。
`FF_USE_ADVANCED_POD_SPEC_CONFIGURATION`	`false`	否	启用后，用户可以在 `config.toml` 文件中设置整个 Pod 规范。更多信息请参见覆盖生成的 Pod 规范（Alpha）。
`FF_SET_PERMISSIONS_BEFORE_CLEANUP`	`true`	否	启用后，首先设置项目目录中的目录和文件权限，以确保清理时可以进行成功删除操作。
`FF_SECRET_RESOLVING_FAILS_IF_MISSING`	`true`	否	启用后，如果找不到该值，secret 解析将失败。
`FF_RETRIEVE_POD_WARNING_EVENTS`	`true`	Yes	启用后，当作业失败时，会检索与 Pod 相关的所有警告事件。这个标志在极狐GitLab Runner 17.2 中已被弃用，并计划在 18.0中移除。在极狐GitLab Runner 17.2 及更高版本中，Pod 警告事件会被无条件地检索和记录。然而，即使缺少 RBAC 权限，也不会发生失败。
`FF_PRINT_POD_EVENTS`	`false`	No	启用后，所有与构建 pod 相关的事件都将会被打印出来，直到它已经启动。
`FF_USE_GIT_BUNDLE_URIS`	`true`	No	启用后，Git `transfer.bundleURI` 配置选项会被设置为 `true`。此 FF 默认情况下开启。设置为 `false` 以禁用 Git bundle 支持。
`FF_USE_DUMB_INIT_WITH_KUBERNETES_EXECUTOR`	`false`	No	启用后，`dumb-init` 被用于执行所有的脚本。这允许 `dumb-init` 作为帮助容器和构建容器中的第一个进程运行。
`FF_USE_INIT_WITH_DOCKER_EXECUTOR`	`false`	No	启用后，Docker 执行器会启动服务并使用 `--init` 参数来构建容器，而且以 PID 1 来运行 `tini-init`。
`FF_LOG_IMAGES_CONFIGURED_FOR_JOB`	`false`	No	启用后，runner 会记录每个接收到的作业所定义的镜像和服务镜像的名称。
`FF_USE_DOCKER_AUTOSCALER_DIAL_STDIO`	`true`	No	启用时（默认启用），使用 `docker system stdio` 来隧道连接到远程 Docker 守护进程。当禁用时，对于 SSH 连接使用原生SSH 隧道，对于 WinRM 连接则首先部署一个 ‘fleeting-proxy’ 辅助二进制文件。
`FF_CLEAN_UP_FAILED_CACHE_EXTRACT`	`false`	No	启用后，构建脚本中会插入命令以检测失败的缓存提取，并清理留下的部分缓存内容。
`FF_USE_WINDOWS_JOB_OBJECT`	`false`	No	启用后，runner 在 Windows 上为每个进程创建作业对象，这些进程是使用 shell 和自定义执行器创建的。为了强制终止进程，runner 会关闭作业对象。这应该会改善难以终止的进程的终止情况。
`FF_TIMESTAMPS`	`false`	No	启用后，时间戳会被添加到每条日志跟踪行的开头。
`FF_DISABLE_AUTOMATIC_TOKEN_ROTATION`	`false`	No	启用后，它限制了自动令牌轮换，并在令牌即将过期时记录一条警告。
`FF_USE_LEGACY_GCS_CACHE_ADAPTER`	`false`	No	启用时，将使用传统的 GCS 缓存适配器。当禁用（默认）时，将使用更新的 GCS 缓存适配器，该适配器使用 Google Cloud Storage 的SDK进行身份验证。这应该解决了传统适配器在某些环境中难以处理的身份验证问题，例如在 GKE 中的工作负载身份配置。
`FF_DISABLE_UMASK_FOR_KUBERNETES_EXECUTOR`	`false`	No	如果启用，将移除使用 Kubernetes 执行器执行的作业中的 `umask 0000` 调用。相反，runner 会尝试发现构建容器运行的用户的用户ID（UID）和组ID（GID）。runner 还会在预定义容器中运行 `chown` 命令来更改工作目录和文件的所有权（在更新源、恢复缓存和下载制品之后）。
`FF_USE_LEGACY_S3_CACHE_ADAPTER`	`false`	No	如果启用，将使用传统的 S3 缓存适配器。当禁用（默认）时，将使用较新的 S3 缓存适配器，该适配器使用 AWS 的 S3 SDK 进行身份验证。这应该解决了传统适配器在诸如自定义 STS 端点等环境中难以处理的身份验证问题。
`FF_GIT_URLS_WITHOUT_TOKENS`	`false`	No	如果启用，极狐GitLab Runner 在 Git 配置或命令执行期间不会在任何地方嵌入作业令牌。相反，它设置了一个 Git 凭据助手，该助手使用环境变量来获取作业令牌。这种方法限制了令牌存储，并减少了泄露的潜在风险。
`FF_WAIT_FOR_POD_TO_BE_REACHABLE`	`false`	No	如果启用，runner 会等待 Pod 状态变为“运行中”，并等待 Pod 准备就绪，其证书已附加。
`FF_USE_NATIVE_STEPS`	`false`	No	如果启用，当使用 `run` 关键字指定某个作业时，使用 Native Step Runner Integration 来执行 steps。此功能仅对支持原生 steps 进程的执行器有用，比如 Docker、Docker Autoscaler 以及 Windows Docker。

在工作流配置中启用功能标志

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

对于所有工作流中的作业（全局）：
```
variables:
  FEATURE_FLAG_NAME: 1
```

对于单个作业：

job:
  stage: test
  variables:
    FEATURE_FLAG_NAME: 1
  script:
  - echo "Hello"

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

为每个 Runner 运行的作业启用功能，您需要指定功能标志为 Runner 配置中的 environment变量。

[[runners]]
  name = "ruby-2.7-docker"
  url = "https://CI/"
  token = "TOKEN"
  limit = 0
  executor = "docker"
  builds_dir = ""
  shell = ""
  environment = ["FEATURE_FLAG_NAME=1"]

在 Runner 配置中启用功能标志

引入于极狐GitLab Runner 13.11。

您可以在 [runners.feature_flags] 下通过指定功能标志进行启用。这个设置可以防止作业覆盖功能标志值。

当您配置这个设置时，一些功能标志也仅可用，因为他们不处理作业的执行方式。

[[runners]]
  name = "ruby-2.7-docker"
  url = "https://CI/"
  token = "TOKEN"
  executor = "docker"
  [runners.feature_flags]
    FF_USE_DIRECT_DOWNLOAD = true