GitHub Actions 怎么用 add-mask 隐藏脚本输出中的临时值

在 GitHub Actions 脚本里临时生成一个值时，关键不是“最后再把日志清理掉”，而是要在第一次可能输出它之前完成遮罩注册。最小顺序是：生成值但不打印 → 发送 ::add-mask::VALUE → 写入 GITHUB_OUTPUT → 在后续步骤使用。

官方地址：https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands

只要临时值可能出现在日志、注释或其他 workflow command 中，就先用 add-mask 注册它；已经注册后，后续日志会把匹配内容替换成 ***。遮罩不会替你生成值，也不会改变脚本变量本身。

先确定这次工作流要保护什么

本文只处理一个 job 内的运行时值，例如临时令牌、一次性标识或脚本计算出的短字符串。它不讨论仓库 Secrets 的配置方式，也不把临时值跨 job 保存到外部密钥存储。

GitHub Actions 的 workflow command 通过标准输出与 runner 通信。::add-mask::{value} 会把指定值登记为需要脱敏的内容；这个动作只对登记之后出现的内容有意义。因此，下面的步骤顺序不能调换：

把工作流文件放到正确入口

在仓库中选择“Code → Add file → Create new file”，文件名填写 .github/workflows/mask-runtime-value.yml。如果仓库已经有工作流，也可以直接在本地编辑同一路径，然后提交到默认分支。

先放入下面这个最小示例。示例中的值只用于演示顺序，不要把真实凭据写进 YAML 或命令行参数。

name: mask-runtime-value

on:
  workflow_dispatch:

jobs:
  mask-demo:
    runs-on: ubuntu-latest
    steps:
      - name: Generate and protect a temporary value
        id: prepare
        shell: bash
        run: |
          # 只在内存中生成临时值，登记前不要打印它
          runtime_value="run-$(date +%s)-$RANDOM"

          # 先注册遮罩，后面的日志和 workflow command 才会脱敏
          echo "::add-mask::$runtime_value"

          # 输出名可以公开，输出值仍由 runner 按遮罩规则处理
          echo "runtime-value=$runtime_value" >> "$GITHUB_OUTPUT"

      - name: Read the protected output
        env:
          RUNTIME_VALUE: ${{ steps.prepare.outputs.runtime-value }}
        run: |
          # 这里故意打印一次，用于在 Actions 日志中确认已被遮罩
          echo "temporary value is $RUNTIME_VALUE"

这里的 id: prepare 让后续步骤可以通过 steps.prepare.outputs.runtime-value 读取输出。输出名是普通字段名，真正需要保护的是它对应的运行时内容。

按顺序保存并运行工作流

1. 保存文件：在编辑器底部选择“Commit changes”，提交到默认分支或一个可合并的分支。
2. 打开入口：进入仓库顶部的“Actions”，在左侧选择 mask-runtime-value。
3. 启动运行：点击“Run workflow”，选择分支后再次点击“Run workflow”。这个示例使用 workflow_dispatch，因此不会因为普通 push 自动触发。
4. 展开步骤：打开本次运行，进入 mask-demo job，再展开“Read the protected output”。

确认状态时看两个位置：第一步和第二步都应是绿色成功状态；第二步日志中的临时值应显示为 ***，而不是形如 run-... 的明文。这个可见状态足以说明遮罩命令在日志输出之前已经生效。

为什么要先遮罩再写 GITHUB_OUTPUT

GITHUB_OUTPUT 是 runner 提供的环境文件。把一行 name=value 追加到它，可以把步骤输出暴露给同一 job 的后续步骤，但它不是“自动加密文件”。如果值先被打印到日志，之后再调用 add-mask，已经产生的日志不会被回溯修改。

官方示例也采用“生成、遮罩、输出”的顺序。需要注意的是，遮罩后的值会被当作 secret 处理，因此不应再把它当成另一个 workflow command 的可见输出；输出名可以继续传递，值在日志中应保持脱敏。

三个容易踩到的顺序问题

先 echo 再 add-mask

下面的写法先把值送进日志，遮罩注册太晚：

# 错误示例：值已经进入日志，后面的遮罩无法回溯清理
echo "temporary value: $runtime_value"
echo "::add-mask::$runtime_value"

修复方法是删除前面的调试输出，或者把它改成只输出长度、固定标签等不包含原值的信息。

把 add-mask 写成普通文本

命令的前缀和分隔符必须完整保留：::add-mask:: 后面直接接要保护的值。不要把它写到 YAML 的注释里，也不要通过会自动改写内容的日志格式化工具发送。

把多行内容当成单行值

本文的示例是单行临时值。若脚本生成的是多行文本，需要分别考虑多行输出的 delimiter 语法、换行中的敏感片段，以及是否真的需要把整段内容传给后续步骤；不要为了方便把多行秘密直接拼进普通日志。

修改后的最终确认

提交前可以按下面的顺序做一次人工检查：

1. 搜索工作流文件，确认临时值第一次被使用前已经出现 ::add-mask::。
2. 确认 echo "name=value" >> "$GITHUB_OUTPUT" 使用的是输出文件，而不是普通标准输出。
3. 确认后续步骤通过 steps..outputs. 读取，并且没有把值写到 issue、summary 或其他注释中。
4. 从 Actions 运行页展开日志，看到成功状态和 *** 遮罩结果后，再把工作流合并到长期分支。

相关问题

add-mask 能隐藏已经打印到日志里的值吗？

不能依赖它清理历史输出。应在首次输出或传给其他 workflow command 之前登记。

为什么输出名还能看到，输出值却是星号？

输出名是工作流结构的一部分，遮罩针对的是运行时值。后续步骤仍可按输出名取值，但日志渲染会隐藏匹配的内容。

add-mask 能替代仓库 Secrets 吗？

不能。它解决的是运行时日志脱敏；长期保存、权限控制和跨 job 共享仍应使用合适的密钥存储。