企业官网建设流程全解析

gh-aw身份认证指南：PAT、GitHub App、OIDC三种方式怎么选

【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw

gh-aw（GitHub Agentic Workflows）身份认证是新手最容易卡住的一步。无论你是用PAT（个人访问令牌）、GitHub App，还是OIDC 短期令牌，选错方式都会导致工作流在推理或写回阶段直接失败。本文用通俗的方式带你一次搞清楚三种认证方式的原理、配置步骤和适用场景，让你 5 分钟选出最适合自己的方案。

一、为什么 gh-aw 需要身份认证？

在写任何配置之前，先理解 gh-aw 中存在的两种认证需求（见 auth.mdx）：

💡 一个常见的误区：把「模型 API Key」（如ANTHROPIC_API_KEY）当成 GitHub 认证。它们解决的是两个不同的问题——前者让 AI 能"思考"，后者让 AI 能"动手"。

二、方式一：PAT（个人访问令牌）——最快上手

PAT 是大多数新手的默认选择：创建一个令牌，存进仓库 Secrets，工作流即可运行。

1. 创建一个 fine-grained PAT

1. 进入 GitHub 的Settings → Developer Settings → Personal access tokens → Fine-grained tokens
2. 填写 Token 名称，Resource owner 选择你的用户账号（不是组织）
3. 在Permissions → Account permissions中，将Copilot Requests设为Read
4. 设置较短的过期时间（如 30 天），点击 Generate token

2. 把 PAT 存入仓库 Secrets

推荐用 CLI 一行搞定：

gh aw secrets set COPILOT_GITHUB_TOKEN --value "<your-pat>"

也可以进入仓库Settings → Secrets and variables → Actions，点击New repository secret手动添加：

3. PAT 的关键注意事项

• 必须用 fine-grained PAT，且 Resource owner 是用户账号。组织账号创建的 PAT 无法用于 Copilot 推理认证
• 拒绝 OAuth 令牌：如果令牌以gho_开头，gh-aw 会在激活阶段直接报错，因为 OAuth 令牌权限过大、无法收敛
• 令牌过期需要手动续期——这是 PAT 最大的运维成本
• 用于 GitHub 通用操作的「魔法密钥」是GH_AW_GITHUB_TOKEN，它不替代COPILOT_GITHUB_TOKEN，两者各司其职

✅ 适合：个人仓库、快速验证、无组织 Copilot 订阅的场景。

三、方式二：GitHub App——短生命周期令牌的安全之选

GitHub App 是面向团队和组织的升级方案：工作流启动时自动铸造（mint）一个短生命周期令牌，工作流结束（无论成功失败）自动吊销。

配置步骤

1. 创建 GitHub App，生成私钥
2. 将 App ID 存入变量、私钥存入 Secrets：

gh variable set APP_ID --body "123456" gh aw secrets set APP_PRIVATE_KEY --value "$(cat private-key.pem)"

3. 在 workflow frontmatter 中声明：

tools: github: toolsets: [repos, issues, pull_requests] github-app: client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} owner: "my-org" # 可选：默认当前仓库所有者 repositories: ["repo1", "repo2"] # 可选：默认仅当前仓库

GitHub App 的三大优势

• 零人工干预：不需要维护令牌生命周期，每次运行自动铸造、自动吊销
• 最小权限：令牌权限精确匹配 job 的permissions:字段；safe outputs 场景下甚至为每个输出类型单独铸造窄权限令牌
• 仓库级范围收敛：repositories字段可把令牌限制在指定仓库，["*"]则代表组织全仓库

两个实用技巧：

• ignore-if-missing: true：当 App 私钥不可用（如 fork 仓库的 PR 场景）时跳过铸造步骤，回退到GH_AW_GITHUB_TOKEN → GITHUB_TOKEN标准令牌链，避免工作流直接失败
• 按 handler 覆盖：在safe-outputs下为不同输出类型配置不同的github-app，例如评论类输出用仅issues: write的小权限 App

✅ 适合：组织级标准化部署、跨仓库 safe outputs、对安全合规有要求的团队。

四、方式三：OIDC——无密钥的终极形态

OIDC（OpenID Connect）是三种方式中安全性最高的：仓库里完全不存放任何长期密钥，工作流运行时用 GitHub 签发的短期 OIDC 令牌去换取 AI 厂商的凭证。

工作原理（以 Claude 引擎的 Anthropic WIF 为例）

1. 工作流 job 声明permissions: id-token: write
2. 运行时 GitHub 签发一个分钟级有效期的 OIDC 令牌
3. AWF 防火墙的 api-proxy 边车拿它去 Anthropic 的联邦规则（Federation Rule）交换短期访问令牌

frontmatter 配置大致如下：

permissions: contents: read id-token: write engine: id: claude auth: type: github-oidc provider: anthropic federation-rule-id: fdrl_xxxxxxxxxxxx organization-id: org_xxxxxxxxxxxx service-account-id: svac_xxxxxxxxxxxx workspace-id: ws_xxxxxxxxxxxx

配置生效后，ANTHROPIC_API_KEY静态密钥要求被自动豁免，编译器会下发AWF_AUTH_ANTHROPIC_*环境变量给防火墙边车。Gemini 引擎同理，通过Google Cloud Workload Identity Federation走 Vertex AI 后端，需配置workload-identity-provider、service-account、project三个字段。

OIDC 的代价

• 需要在 AI 厂商侧预先配置联邦规则 / WIF Provider（一次性运维工作）
• 多出的配置字段对新手工单
• 部分厂商的 WIF 功能需对应版本支持（如 Anthropic WIF 自 v0.79.6 起可用）

✅ 适合：企业合规要求「仓库零长期密钥」、使用 Google Cloud / Anthropic 企业账号的团队。

五、三种方式怎么选？一张表说清楚

一句话选型建议：

• 🚀 刚上手、个人仓库 →PAT（配合copilot-requests: write权限甚至可免 PAT）
• 🏢 团队协作、跨仓库操作 →GitHub App
• 🔒 企业合规、拒绝任何长期密钥 →OIDC + WIF

💡 隐藏的第四选项：如果组织开通了 Copilot 集中计费，在permissions:里加一行copilot-requests: write，gh-aw 会直接使用每次运行铸造的${{ github.token }}，连 PAT 都不需要。

六、常见认证错误速查

七、延伸阅读

• 完整认证参考文档：docs/src/content/docs/reference/auth.mdx
• Projects 专项认证：docs/src/content/docs/reference/auth-projects.mdx
• 快速上手指南：docs/src/content/docs/setup/quick-start.mdx
• 权限模型说明：docs/src/content/docs/reference/permissions.md
• 故障排查手册：docs/src/content/docs/troubleshooting/common-issues.md

按「先 PAT 跑通、再 GitHub App 上组织、最后 OIDC 收口密钥」的路线演进，你的 gh-aw 认证体系就能平滑升级，不用推倒重来。

【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw