GitHub 项目环境变量与密钥的分层配置

GitHub 项目里的配置不要全部堆在仓库级。一个更稳的分层方式是：公开或非敏感的运行参数放到 Variables，令牌、密码、证书内容放到 Secrets；跨多个仓库复用的值放在组织层，单个仓库通用的值放在仓库层，只属于 staging 或 production 的值放在环境层。

官方地址：https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables

最容易出错的地方不是字段怎么填，而是 job 有没有声明正确的 environment。仓库级值可以直接被该仓库的工作流使用；环境级变量和密钥要等 job 绑定到对应环境后才有意义，环境密钥还可能被 required reviewers 拦住。

先把配置分成 Variables 和 Secrets

打开仓库的 Settings，进入 Secrets and variables → Actions，页面通常会分别提供 Variables 与 Secrets 标签。变量适合部署区域、镜像标签、开关名等不需要保密的值；密钥适合 API token、云端访问凭据和签名材料。GitHub 文档说明，Actions secrets 可以定义在组织、仓库或仓库环境中，工作流必须显式把它作为输入或环境变量使用。

这两个集合的读取语法也不同：配置变量用 ${{ vars.DEPLOY_REGION }}，密钥用 ${{ secrets.DEPLOY_TOKEN }}。名称可以相似，但存储位置和泄露后果完全不同。不要把真实 token 写进工作流文件、示例代码或普通变量。

在仓库层配置所有该项目都能使用的值

1. 进入入口：打开仓库首页，点击 Settings，左侧进入 Secrets and variables → Actions。
2. 新增普通变量：点击 Variables → New repository variable，在 Name 填 DEPLOY_REGION，在 Value 填非敏感区域值，再点 Add variable。
3. 新增密钥：切换到 Secrets → New repository secret，填入 DEPLOY_TOKEN 和真实密钥，再点 Add secret。文章示例不填真实值；保存后不要再尝试通过日志读取它。

回到列表后，能看到变量名称和密钥名称，密钥的值不会作为明文展示。这个可见状态只说明条目已经创建，不代表某个工作流已经引用它；下一步仍要在 YAML 中显式绑定。

把 staging 和 production 的差异放进 Environment

环境层适合同一个仓库的不同发布目标。例如 staging 使用测试服务地址，production 使用正式服务地址和更严格的审批。操作路径是：仓库 Settings → Environments → 选择或创建 production → 在 Environment variables 下点击 Add variable；要保存敏感值，则在同一环境的 Environment secrets 区域添加密钥。

如果发布环境需要人工确认，可在该环境的保护规则中配置 required reviewers。环境密钥不会因为名字相同就自动替代仓库密钥；先看 job 是否声明了目标环境，再判断它实际拿到的是哪一层值。

在工作流中显式绑定作用域

下面的最小示例把环境名称写在 job 上，把配置变量用于普通参数，把密钥作为步骤环境变量传给动作。代码中的名称都是占位符，实际项目应按自己的权限模型命名：

name: deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    # 只有声明 environment 后，production 层的值才参与这个 job。
    environment: production
    runs-on: ubuntu-latest
    steps:
      - name: 发布服务
        # vars 读取非敏感配置，secrets 读取敏感凭据。
        env:
          REGION: ${{ vars.DEPLOY_REGION }}
          TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          # 不打印 TOKEN；这里只展示把它传给发布命令的边界。
          ./deploy --region "$REGION" --token "$TOKEN"

这里的关键检查点有三个：environment: production 是否拼写正确；变量名是否和设置页完全一致；命令是否避免把 TOKEN 拼进日志、错误信息或调试输出。GitHub 的 vars、secrets、env 都是不同上下文，不要把它们当成同一个字典。

用三个可见信号完成验收

如果多个层级使用同名配置，最好改成带作用域语义的名称，例如 STAGING_API_BASE 与 PROD_API_BASE，减少读者对覆盖关系的猜测。组织变量还应设置仓库访问策略，只让需要它的仓库可用。

常见问题

仓库变量和环境变量能不能使用同一个名字？

可以存在同名配置，但不建议把覆盖关系当成主要设计。优先使用带环境语义的名称，并在 job 上显式声明 environment，排查时更容易知道值从哪里来。

为什么设置了环境密钥，工作流里还是读不到？

先检查 job 是否写了对应的 environment，再检查环境保护规则是否仍在等待审批。只在设置页创建密钥，不会让没有绑定环境的 job 自动获得它。

能不能用 echo 检查 secret 是否配置成功？

不要打印 secret 值。可以检查变量是否为空、观察 job 的审批状态，并让实际动作返回不包含凭据的成功或失败信息。

总结一下：先按敏感性选择 Variables 或 Secrets，再按共享范围选择组织、仓库或环境，最后在 job 中显式声明 environment 并用正确上下文读取。这样设置页的层级、工作流的引用和运行时的审批状态能够互相对应。