GitHub Actions 代理任务怎样设计可追溯的权限边界

GitHub Actions 中的代理任务应把“读取并提出建议”“写回仓库”“访问部署资源”拆成权限独立的任务，再用运行标识、尝试次数和提交标识关联记录。提示词里的“不要部署”只能表达意图，真正的限制必须落在令牌权限、执行环境与外部服务的授权规则上。

官方地址：https://docs.github.com/en/actions

本文把代理任务理解为调用自动化助手分析内容、生成建议或产物的 Actions 作业，不假定某个具体代理产品具有相同权限模型。采用一个最小配方，再讨论评论和部署变体；文中的方案没有在真实仓库运行，也不声称已经完成安全测试。

先把代理建议与外部写入分开

假设团队希望代理阅读 PR、解释变更并生成修改建议。任务的必要结果是建议文本，并不天然包含推送提交、合并 PR 或发布到生产环境。如果把全部能力交给同一个作业，PR 内容、仓库脚本和代理工具都可能接触同一组凭据，事后也很难区分哪一步真正需要写权限。

先列四类对象：输入内容、代理进程、写回接口、部署目标。输入可以影响分析内容，不能自行决定访问哪个仓库、切换哪个环境或扩大令牌范围。代理输出应被当成待处理的数据；后续作业可以校验其格式、长度和允许动作，不应直接把输出当成任意 shell 命令执行。

最小配方是一张逐任务权限表

这张表是职责设计，不是平台自动生成的隔离保证。拆成不同作业后，仍要检查共享 runner、缓存、产物与长期凭据是否把权限重新连接起来。分析任务若需要调用外部模型服务，还应单独管理服务凭据、数据发送范围和用量，不把“仓库只读”误解为“没有外部访问能力”。

GitHub 的 工作流语法文档支持在 permissions 中明确声明 read、write 或 none；声明了部分权限后，未声明项设为 none。建议在工作流层收紧默认值，再逐作业开放必要项。此设置控制 GITHUB_TOKEN，不能收回你另外传入的 PAT、GitHub App 凭据或云密钥。

关键配置需要同时限制身份和输入

对来自 fork 或其他不受信任来源的内容，要同时问两个问题：该事件给了任务什么能力，任务会执行哪些内容。不能只看事件名称就推断所有输入安全，也不能认为静态提示词能覆盖仓库脚本实际行为。

GitHub 的 pull_request_target 安全说明明确警告：不要在可访问仓库 secrets 或高权限 GITHUB_TOKEN 的作业中检出、构建或运行不可信 PR 代码。评论这种管理操作与执行提交代码属于不同信任要求，应分别设计。

评论变体也要限制目标。建议把仓库和 PR 标识取自可信的工作流上下文或经过核对的记录，不接受代理输出任意指定目标；发布前对建议产物做结构化处理。若使用独立工作流接收分析产物，应检查来源仓库、运行、工作流、提交和预期产物的对应关系。单纯“下载了某个同名文件”不能证明它来自本次分析。

部署变体把云权限留在专用任务

部署作业可以使用 OIDC 申请短期身份。id-token: write 允许请求 OIDC token，本身不赋予云资源写权限；云端还要配置可信身份条件和角色权限。不要把“能够拿到 token”写成“已经获准部署任意资源”。依据见 GitHub OIDC 云端配置说明。

建议云端信任策略限定预期仓库和适用的分支、环境或可复用工作流身份，并限定 audience。具体字段和匹配语法由云提供商决定，不能复制一种提供商的策略到另一种服务。OIDC 参考列出了可用声明，实际策略应与令牌中的身份语义对应。

环境保护需要提前配置。管理员可从仓库 Settings 的 Environments 进入环境，按可用功能设置允许部署的分支、审阅要求等。引用一个不存在的环境可能创建没有保护规则的环境，因此环境名称应由维护配置确定，不让代理自由生成。保护规则的可用性与套餐、仓库可见性有关，不能在设计里假定每个私有仓库都有同样的审批能力。

规则和配置入口参见 环境管理文档。批准的对象还应明确到提交和产物；审阅者看到的是建议，并不自动表示另一份后来生成的产物也得到同意。

追溯记录区分运行与重试

建议用“仓库 + run_id + run_attempt + job”作为一次任务尝试的关联键，并记录事件、实际输入提交、工作流版本、输出产物和外部操作标识。GitHub 默认变量中的 GITHUB_RUN_ID 标识工作流运行，GITHUB_RUN_ATTEMPT 区分重跑尝试；只记录前者会把重试混在一起。默认变量定义见 官方变量参考。

PR 事件中的提交语义也要写清：触发工作流的提交、PR head 和实际检出的提交不应含糊地都叫“SHA”。对于产物，建议记录摘要和来源，而不是把文件名当成身份。记录有助于关联，但单独一行日志不是不可篡改证明，保留期限和读取权限同样需要维护。

记录失败时也要区分外部操作结果。如果评论 API 超时，不应直接认定“肯定没写入”并无限重试；应用应保留请求上下文，按接口能力处理重复操作。日志中不要保存完整 token、认证头或敏感模型输入，关联标识不需要以泄露凭据为代价。

把完整配方交给维护者

最终交付可以是一组明确约束：分析只产出建议，评论只写固定目标，部署只接受已确认的产物；每项使用单独的作业权限；外部身份由目标系统再次授权；每次尝试保留输入、产物与操作关联。第三方 action 和代理工具也应有明确版本与维护来源，避免依赖变化使权限表失去对应对象。

给代理设置只读 GITHUB_TOKEN 就够了吗？不够。还要查看其他 secrets、runner 文件和网络权限、外部工具身份；这些能力不由 GITHUB_TOKEN 的 contents 权限统一控制。

有环境审批就能运行任意代理输出吗？不能。审批决定是否放行特定操作，不会自动把任意文本转成可信程序。部署作业应使用维护者控制的执行逻辑和受限输入。

为什么重跑也要重新记录？输入、工具结果或外部状态可能变化。独立的 attempt 记录能说明哪次尝试产生了哪个评论或部署结果，避免把首次失败和后续成功混为一条记录。