如何审计gh-aw生成的.lock.yml文件部署前7项人工审查完整清单【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-awgh-awGitHub Agentic Workflows可以把 Markdown 编写的 AI 代理工作流一键编译成 GitHub Actions 可执行的.lock.yml工作流文件。由于编译产物会带着 Token、Secrets 在 CI 环境中运行 AI Agent部署前的人工审查至关重要。本文给出一份面向新手和运维人员的「.lock.yml 审计清单」7 项检查逐层把关帮你快速发现权限过大、依赖漂移和模板注入等常见风险。一、先搞懂.lock.yml 从哪里来一个 agentic workflow 由两部分组成YAML frontmatter配置触发器、权限、工具、AI 引擎和 Markdown 正文给 AI 的指令。运行gh aw compile后编译器会执行「解析 → 校验 → 任务构建 → 依赖解析 → YAML 生成」5 个阶段输出标准的.lock.yml.github/ └── workflows/ ├── ci-doctor.md # 你编写的 Agentic 工作流源文件 └── ci-doctor.lock.yml # 编译生成的 GitHub Actions 工作流要点.lock.yml文件头部标注了DO NOT EDIT——它是自动生成的任何修改都应回到.md源文件再重新编译。审查时你要核对的正是「源文件意图」与「编译产物」是否一致。更多细节可参考 workflow-structure.md 与 compilation-process.md。二、部署前 7 项人工审查清单✅ 检查 1核对 gh-aw-metadata 元数据行每个.lock.yml的第一行都是机器可读的元数据# gh-aw-metadata: {schema_version:v4,frontmatter_hash:...,body_hash:...,strict:true,agent_id:copilot}人工核对三件事字段你要确认的事schema_version是否为最新版本当前为v4过旧说明编译器版本滞后frontmatter_hash/body_hash与最近一次编译是否匹配防止源文件改了、lock 没重新编译strict生产环境建议为true严格模式 如果只改了 Markdown 正文建议给 frontmatter 加上on.stale-check: full运行时会用body_hash做完整漂移检测源文件与锁文件不一致时直接失败fail-closed。设计背景见 ADR-34941。✅ 检查 2比对 Secrets used 清单元数据行下方有一份人类可读的依赖清单其中Secrets used:段落列出了编译产物中所有secrets.*引用已排序去重# Secrets used: # - COPILOT_GITHUB_TOKEN # - GITHUB_TOKEN审查动作逐一确认每个 Secret 都是必要的删除清单中出现但你不知道用途的密钥引用。Secrets 是 Agent 工作流中最敏感的凭证最小化原则在这里尤其重要。✅ 检查 3验证所有 Action 依赖已用 SHA 固定Custom actions used:段落列出全部外部uses:依赖。安全要求每个 Action 都必须锚定到不可变的 commit SHA并附版本注释而不是v4、main这类可变引用# Custom actions used: # - actions/checkoutde0fac2e... # v6.0.2 # - actions/upload-artifactbbbca2... # v4❌ 看到latest、main或裸 tag → 供应链风险需排查编译器版本或action_pins.json配置✅ SHA 固定 版本号注释 → 通过gh-aw 编译器默认就按 SHA 解析 github/gh-aw-actions 中的可复用 ActionSHA 不可用时才退化为v0这类稳定 tag审查时重点看第三方 Action。✅ 检查 4确认 Agent 任务是只读的写操作走 safe-outputsgh-aw 的安全模型是「Agent 只读 沙箱写操作独立授权」在.lock.yml的 Agent job 上检查permissions:应为read-all或最小只读集合检查是否有safe-outputs派生的独立 job 负责创建 Issue / PR / 评论且该 job 仅声明所需的最小写权限如issues: write确认 Agent job 没有拿到contents: write、packages: write等高权限写权限应只出现在经过校验的 safe-outputs job 中详细规范见 safe-outputs.md。✅ 检查 5排查表达式中的模板注入风险在.lock.yml全文搜索${{重点看不可信输入issue 标题、PR 正文、评论、分支名是否直接拼进表达式。安全写法是表达式 → 环境变量 → 脚本的间接模式# ❌ 危险issue 标题直接进表达式 run-name: Processing ${{ github.event.issue.title }} # ✅ 安全经环境变量传入作为数据而非代码 - env: ISSUE_TITLE: ${{ github.event.issue.title }}gh-aw 本身对注入表达式做了净化处理但人工审查仍要确认没有绕过环境变量直接拼接不可信上下文的残留。检查依据可参考 github-actions-security-best-practices.md。✅ 检查 6确认源文件与锁文件成对提交.md源文件和.lock.yml必须一起提交只提交其中一个都会导致漂移用gh aw compile --purge清理孤儿锁文件源文件已删除但 lock 还在的残留diff 一下.lock.yml的变化范围只改了一行正文却出现大面积 diff 时多半是编译器版本跳变需人工确认✅ 检查 7跑一遍编译校验再看运行日志提交前本地执行gh aw compile确保零报错、零警告首次运行后打开 Actions 运行记录核对「Check workflow lock file」步骤通过锁文件新鲜度校验下图是一个 CI 故障调查型 agentic 工作流的真实运行输出可作为运行结果审查的参考样例三、推荐部署前审查流程gh aw compile本地编译通过无警告打开.lock.yml按上文 7 项清单自上而下检查元数据 → Secrets → SHA 固定 → 权限 → 表达式 → 提交完整性 → 运行校验高风险变更新增 Secret、新增第三方 Action、扩大权限要求第二人复核合入后观察一次真实运行确认锁文件校验步骤通过四、延伸阅读与相关模块工作流结构与锁文件头部格式docs/src/content/docs/reference/workflow-structure.md编译流程 5 阶段详解docs/src/content/docs/reference/compilation-process.mdsafe-outputs 权限模型docs/src/content/docs/reference/safe-outputs.md锁文件元数据与 stale-check 设计决策docs/adr/34941-body-hash-in-lock-metadata-and-stale-check-full.md编译器源码生成锁文件的核心逻辑pkg/workflow/Action 固定pin解析实现pkg/actionpins/安全最佳实践清单scratchpad/github-actions-security-best-practices.md架构与威胁模型specs/security-architecture-spec.md 一句话总结.lock.yml是 AI 工作流的「登机牌」7 项清单逐项打钩再让 Agent 起飞。【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何审计gh-aw生成的.lock.yml文件：部署前7项人工审查完整清单
如何审计gh-aw生成的.lock.yml文件部署前7项人工审查完整清单【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-awgh-awGitHub Agentic Workflows可以把 Markdown 编写的 AI 代理工作流一键编译成 GitHub Actions 可执行的.lock.yml工作流文件。由于编译产物会带着 Token、Secrets 在 CI 环境中运行 AI Agent部署前的人工审查至关重要。本文给出一份面向新手和运维人员的「.lock.yml 审计清单」7 项检查逐层把关帮你快速发现权限过大、依赖漂移和模板注入等常见风险。一、先搞懂.lock.yml 从哪里来一个 agentic workflow 由两部分组成YAML frontmatter配置触发器、权限、工具、AI 引擎和 Markdown 正文给 AI 的指令。运行gh aw compile后编译器会执行「解析 → 校验 → 任务构建 → 依赖解析 → YAML 生成」5 个阶段输出标准的.lock.yml.github/ └── workflows/ ├── ci-doctor.md # 你编写的 Agentic 工作流源文件 └── ci-doctor.lock.yml # 编译生成的 GitHub Actions 工作流要点.lock.yml文件头部标注了DO NOT EDIT——它是自动生成的任何修改都应回到.md源文件再重新编译。审查时你要核对的正是「源文件意图」与「编译产物」是否一致。更多细节可参考 workflow-structure.md 与 compilation-process.md。二、部署前 7 项人工审查清单✅ 检查 1核对 gh-aw-metadata 元数据行每个.lock.yml的第一行都是机器可读的元数据# gh-aw-metadata: {schema_version:v4,frontmatter_hash:...,body_hash:...,strict:true,agent_id:copilot}人工核对三件事字段你要确认的事schema_version是否为最新版本当前为v4过旧说明编译器版本滞后frontmatter_hash/body_hash与最近一次编译是否匹配防止源文件改了、lock 没重新编译strict生产环境建议为true严格模式 如果只改了 Markdown 正文建议给 frontmatter 加上on.stale-check: full运行时会用body_hash做完整漂移检测源文件与锁文件不一致时直接失败fail-closed。设计背景见 ADR-34941。✅ 检查 2比对 Secrets used 清单元数据行下方有一份人类可读的依赖清单其中Secrets used:段落列出了编译产物中所有secrets.*引用已排序去重# Secrets used: # - COPILOT_GITHUB_TOKEN # - GITHUB_TOKEN审查动作逐一确认每个 Secret 都是必要的删除清单中出现但你不知道用途的密钥引用。Secrets 是 Agent 工作流中最敏感的凭证最小化原则在这里尤其重要。✅ 检查 3验证所有 Action 依赖已用 SHA 固定Custom actions used:段落列出全部外部uses:依赖。安全要求每个 Action 都必须锚定到不可变的 commit SHA并附版本注释而不是v4、main这类可变引用# Custom actions used: # - actions/checkoutde0fac2e... # v6.0.2 # - actions/upload-artifactbbbca2... # v4❌ 看到latest、main或裸 tag → 供应链风险需排查编译器版本或action_pins.json配置✅ SHA 固定 版本号注释 → 通过gh-aw 编译器默认就按 SHA 解析 github/gh-aw-actions 中的可复用 ActionSHA 不可用时才退化为v0这类稳定 tag审查时重点看第三方 Action。✅ 检查 4确认 Agent 任务是只读的写操作走 safe-outputsgh-aw 的安全模型是「Agent 只读 沙箱写操作独立授权」在.lock.yml的 Agent job 上检查permissions:应为read-all或最小只读集合检查是否有safe-outputs派生的独立 job 负责创建 Issue / PR / 评论且该 job 仅声明所需的最小写权限如issues: write确认 Agent job 没有拿到contents: write、packages: write等高权限写权限应只出现在经过校验的 safe-outputs job 中详细规范见 safe-outputs.md。✅ 检查 5排查表达式中的模板注入风险在.lock.yml全文搜索${{重点看不可信输入issue 标题、PR 正文、评论、分支名是否直接拼进表达式。安全写法是表达式 → 环境变量 → 脚本的间接模式# ❌ 危险issue 标题直接进表达式 run-name: Processing ${{ github.event.issue.title }} # ✅ 安全经环境变量传入作为数据而非代码 - env: ISSUE_TITLE: ${{ github.event.issue.title }}gh-aw 本身对注入表达式做了净化处理但人工审查仍要确认没有绕过环境变量直接拼接不可信上下文的残留。检查依据可参考 github-actions-security-best-practices.md。✅ 检查 6确认源文件与锁文件成对提交.md源文件和.lock.yml必须一起提交只提交其中一个都会导致漂移用gh aw compile --purge清理孤儿锁文件源文件已删除但 lock 还在的残留diff 一下.lock.yml的变化范围只改了一行正文却出现大面积 diff 时多半是编译器版本跳变需人工确认✅ 检查 7跑一遍编译校验再看运行日志提交前本地执行gh aw compile确保零报错、零警告首次运行后打开 Actions 运行记录核对「Check workflow lock file」步骤通过锁文件新鲜度校验下图是一个 CI 故障调查型 agentic 工作流的真实运行输出可作为运行结果审查的参考样例三、推荐部署前审查流程gh aw compile本地编译通过无警告打开.lock.yml按上文 7 项清单自上而下检查元数据 → Secrets → SHA 固定 → 权限 → 表达式 → 提交完整性 → 运行校验高风险变更新增 Secret、新增第三方 Action、扩大权限要求第二人复核合入后观察一次真实运行确认锁文件校验步骤通过四、延伸阅读与相关模块工作流结构与锁文件头部格式docs/src/content/docs/reference/workflow-structure.md编译流程 5 阶段详解docs/src/content/docs/reference/compilation-process.mdsafe-outputs 权限模型docs/src/content/docs/reference/safe-outputs.md锁文件元数据与 stale-check 设计决策docs/adr/34941-body-hash-in-lock-metadata-and-stale-check-full.md编译器源码生成锁文件的核心逻辑pkg/workflow/Action 固定pin解析实现pkg/actionpins/安全最佳实践清单scratchpad/github-actions-security-best-practices.md架构与威胁模型specs/security-architecture-spec.md 一句话总结.lock.yml是 AI 工作流的「登机牌」7 项清单逐项打钩再让 Agent 起飞。【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考