控制 GITHUB_TOKEN 的权限

修改授予 GITHUB_TOKEN 的默认权限。

本文内容

概述

可以使用 permissions 修改授予 GITHUB_TOKEN 的默认权限，根据需要添加或删除访问权限，以便只授予所需的最低访问权限。 有关详细信息，请参阅“自动令牌身份验证”。

可以使用 permissions 作为顶级密钥，以应用于工作流中的所有作业或特定作业。 当你在特定作业中添加 permissions 密钥时，该作业中使用 GITHUB_TOKEN 的所有操作和运行命令都将获得你指定的访问权限。 有关详细信息，请参阅 jobs.<job_id>.permissions。

对于下表中显示的每个可用权限，可以分配以下访问级别之一：read（如果适用）、write 或 none。 write 包括 read。 如果指定其中任何权限的访问，则所有未指定的权限都将设置为 none。

可用的权限以及每个权限允许执行的操作的详细信息：

权限允许操作使用 GITHUB_TOKEN
actions使用 GitHub Actions。 例如，actions: write 允许操作取消工作流运行。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。
attestations使用项目证明。 例如，attestations: write 允许一个操作为生成生成项目证明。 有关详细信息，请参阅“使用项目证明确立生成的来源”。
checks使用检查运行和检查套件。 例如，checks: write 允许操作创建检查运行。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。
contents处理存储库的内容。 例如，contents: read 允许操作列出提交，contents: write 允许操作创建发布。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。
deployments处理部署。 例如，deployments: write 允许操作创建新部署。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。
discussions使用 GitHub Discussions。 例如，discussions: write 允许操作关闭或删除讨论。 有关详细信息，请参阅“使用 GraphQL API for Discussions”。
id-token提取 OpenID Connect (OIDC) 令牌。 这需要 id-token: write。 有关详细信息，请参阅“关于使用 OpenID Connect 进行安全强化”。
issues处理问题。 例如，issues: write 允许操作向问题添加注释。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。
packages使用 GitHub Packages。 例如，packages: write 允许操作在 GitHub Packages 上上传和发布包。 有关详细信息，请参阅“关于 GitHub Packages 的权限”。
pages使用 GitHub Pages。 例如，pages: write 允许操作请求 GitHub Pages 生成。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。
pull-requests处理拉取请求。 例如，pull-requests: write 允许操作向拉取请求添加标签。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。
repository-projects使用 GitHub 项目（经典）。 例如，repository-projects: write 允许操作向项目添加列（经典）。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。
security-events使用 GitHub 代码扫描和 Dependabot 警报。 例如，security-events: read 允许操作列出存储库的 Dependabot 警报，security-events: write 允许操作更新代码扫描警报的状态。 有关详细信息，请参阅“GitHub 应用所需的权限”中的“‘代码扫描警报’的存储库权限”和“‘Dependabot 警报’的存储库权限”。
statuses处理提交状态。 例如，statuses:read 允许操作列出给定引用的提交状态。 有关详细信息，请参阅“GitHub 应用程序所需的权限”。

定义 GITHUB_TOKEN 权限的访问权限

可以通过将 read、write 或 none 指定为 permissions 键中可用权限的值来定义 GITHUB_TOKEN 将允许的访问。

permissions:
  actions: read|write|none
  attestations: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

如果指定其中任何权限的访问，则所有未指定的权限都将设置为 none。

可以使用以下语法来定义所有可用权限的 read-all 或 write-all 访问：

permissions: read-all

permissions: write-all

可以使用以下语法来禁用所有可用权限的权限：

permissions: {}

更改分支存储库中的权限

可以使用 permissions 密钥添加和删除分叉存储库的读取权限，但通常不能授予其写入权限。 此行为的例外情况是，管理员用户已在 GitHub Actions 设置中选择了“通过拉取请求向工作流发送写入令牌”选项。 有关详细信息，请参阅“管理存储库的 GitHub Actions 设置”。

为工作流中的所有作业设置 GITHUB_TOKEN 权限

可以在工作流的顶层指定 permissions，以便设置应用于工作流中的所有作业。

示例：为整个工作流设置 GITHUB_TOKEN 权限

此示例显示为将要应用到工作流中所有作业的 GITHUB_TOKEN 设置的权限。 所有权限都被授予读取权限。

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

为特定作业设置 GITHUB_TOKEN 权限

在特定的作业中，你可以使用 jobs.<job_id>.permissions 修改授予 GITHUB_TOKEN 的默认权限，根据需要添加或删除访问权限，以便只授予所需的最低访问权限。 有关详细信息，请参阅“自动令牌身份验证”。

通过在作业定义中指定权限，可根据需要为每个作业的 GITHUB_TOKEN 配置一组不同的权限。 或者，您也可以为工作流程中的所有作业指定权限。 有关在工作流级别定义权限的信息，请参阅 permissions。

示例：为工作流中的一个作业设置 GITHUB_TOKEN 权限

本示例显示为将仅应用到作业 stale 的 GITHUB_TOKEN 设置的权限。 为 issues 和 pull-requests 权限授予写入权限。 所有其他权限均无权访问。

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5