GitHub Actions 可复用工作流的输入边界变化

把一段 GitHub Actions 配置改成可复用工作流时，最容易踩的坑不是 uses 写错，而是输入契约变了：被调用工作流要在 on.workflow_call.inputs 中声明字段和类型，调用方只能在 with 中传已声明的值，被调用侧再通过统一的 inputs 上下文读取。这样迁移后，参数不会再靠字符串约定“猜”类型。

官方文档地址：https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows

输入边界可以按“声明—传值—读取—结果”四段检查。workflow_call 支持 boolean、number 和 string；没有显式默认值时，空值也会按类型落到 false、0 或空字符串。手动触发工作流与可复用工作流可以共用 inputs 上下文，但密钥不应混进普通输入。

• 声明边界：类型、是否必填和默认值写在被调用工作流。
• 传值边界：调用方使用 jobs..with，字段名必须存在。
• 读取边界：业务条件优先读 inputs.，不要把布尔值当字符串比较。
• 敏感边界：令牌放在 secrets，嵌套调用时仍要继续传递。

先把两种触发方式的输入契约分开

旧配置常把手动触发和复用调用写成两套字段：workflow_dispatch 的值从事件载荷读取，可复用工作流则从 workflow_call 定义输入。GitHub 后来统一了 inputs 上下文，所以同一份业务判断可以同时服务手动触发与复用调用；github.event.inputs 仍可用于兼容旧的手动触发写法，但不应继续把它当作可复用工作流的主接口。

这里的“变化”不是把所有输入类型都混为一谈：workflow_call 的输入类型是 boolean、number、string，而手动触发还可能使用选择项或环境项。迁移前先确认触发器，再决定声明格式。

把类型和默认值放在被调用工作流

被调用工作流是输入契约的源头。下面的例子把部署目标设为必填字符串，把是否执行检查设为可选布尔值。字段名、类型和默认值都在这里固定，调用方只负责提供值。

name: Reusable verify

on:
  workflow_call:
    inputs:
      target:
        description: 部署目标名称
        required: true
        type: string
      run-checks:
        description: 是否执行额外检查
        required: false
        default: false
        type: boolean

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - name: 检查输入
        if: ${{ inputs.run-checks }}
        run: echo "检查目标 ${{ inputs.target }}"
        # 这里直接使用布尔上下文，不把 true 拼成字符串再判断。

如果可选字段没有写默认值，GitHub 会按声明类型提供默认值；如果调用方传入被调用工作流没有声明的字段，则会直接报错。这个边界很有用：新增输入时必须同时更新契约和调用方，遗漏不会悄悄变成环境变量。

调用方只在 with 中传已声明的值

调用工作流的 job 不是普通 step。它使用 uses 指向可复用工作流，再用 with 传普通参数；不要把同名参数写到 step 的 env 后期待它自动成为 workflow_call 输入。对跨仓库调用，引用的分支、标签或提交也应按团队发布策略固定。

jobs:
  call-verify:
    uses: octo-org/platform/.github/workflows/reusable-verify.yml@main
    with:
      target: staging
      run-checks: true
    secrets:
      deploy-token: ${{ secrets.DEPLOY_TOKEN }}
      # 普通输入与敏感值分开，避免把令牌放进 with。

调用方传递的值必须匹配被调用侧的类型。尤其是布尔输入，不要把 'true' 当成普通字符串后再在工作流内部做文本比较；条件表达式直接读取 inputs.run-checks 更清楚。若要让同一组织或企业中的工作流隐式获得可用密钥，也应明确写出 secrets: inherit 的适用范围，而不是把所有上下文都当成公开参数。

把 inputs、secrets 和嵌套调用分成三条链

迁移时可以把数据流画成三条链：普通参数从 workflow_call.inputs 进入 with，再由 inputs 读取；敏感值从 workflow_call.secrets 进入 secrets；输出则从被调用工作流的 job 输出映射回调用方。三者名字可以相似，但校验和暴露边界不同。

如果可复用工作流继续调用另一个可复用工作流，密钥不能因为上一层已经收到就自动穿透到下一层；需要在嵌套 job 上再次传递。相反，普通输入也应在每一层重新声明，保持每个工作流对自己依赖的字段可读。

用五项清单完成迁移

1. 确认被调用文件位于仓库的 .github/workflows 目录，并包含 workflow_call。
2. 逐项登记输入的类型、必填状态和默认值；没有默认值时记住三种类型的空值差异。
3. 检查调用 job 的 with 字段，删除未声明字段，修正布尔值和数字值的写法。
4. 把令牌、密码等敏感内容移到 secrets，检查嵌套调用是否再次传递。
5. 把被调用工作流内部的旧式事件读取替换为 inputs.，并为手动触发保留兼容说明。

常见问题

为什么调用方多写一个参数就失败？

因为可复用工作流的输入是显式契约。调用方传入的字段必须在被调用工作流的 on.workflow_call.inputs 中声明，不能用环境变量或任意 YAML 字段绕过。

没有写 default 时布尔值是什么？

对于可选的布尔输入，默认值是 false；数字是 0，字符串是空字符串。若业务上必须区分“没传”和“明确传 false”，就不能只依靠这个默认值。

workflow_dispatch 还能读 github.event.inputs 吗？

旧的手动触发写法仍有兼容空间，但新配置更适合统一读取 inputs。这样同一工作流同时支持手动触发和可复用调用时，业务条件只保留一套读取路径。