控制 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 Apps所需的权限”。
attestations使用工件证明。例如，attestations: write 允许操作为构建生成工件证明。更多信息，请参见“使用工件证明建立构建来源”
checks使用检查运行和检查套件。例如，checks: write 允许操作创建检查运行。更多信息，请参见“GitHub Apps所需的权限”。
contents使用仓库的内容。例如，contents: read 允许操作列出提交，而 contents: write 允许操作创建发布。更多信息，请参见“GitHub Apps所需的权限”。
deployments使用部署。例如，deployments: write 允许操作创建新的部署。更多信息，请参见“GitHub Apps所需的权限”。
discussions使用 GitHub Discussions。例如，discussions: write 允许操作关闭或删除讨论。更多信息，请参见“使用 GraphQL API 进行讨论”
id-token获取 OpenID Connect (OIDC) 令牌。这需要 id-token: write。更多信息，请参见“关于使用 OpenID Connect 加强安全性”
issues使用 Issues。例如，issues: write 允许操作向 Issue 添加评论。更多信息，请参见“GitHub Apps所需的权限”。
packages使用 GitHub Packages。例如，packages: write 允许操作上传和发布 GitHub Packages 上的包。更多信息，请参见“关于 GitHub Packages 的权限”。
pages使用 GitHub Pages。例如，pages: write 允许操作请求 GitHub Pages 构建。更多信息，请参见“GitHub Apps所需的权限”。
pull-requests使用 Pull Requests。例如，pull-requests: write 允许操作向 Pull Request 添加标签。更多信息，请参见“GitHub Apps所需的权限”。
repository-projects使用 GitHub 项目（经典版）。例如，repository-projects: write 允许操作向项目（经典版）添加列。更多信息，请参见“GitHub Apps所需的权限”。
security-events使用 GitHub 代码扫描和 Dependabot 警报。例如，security-events: read 允许操作列出仓库的 Dependabot 警报，而 security-events: write 允许操作更新代码扫描警报的状态。更多信息，请参见“代码扫描警报的仓库权限”和“Dependabot 警报的仓库权限”（在“GitHub Apps所需的权限”中）。
statuses使用提交状态。例如，statuses:read 允许操作列出给定引用的提交状态。更多信息，请参见“GitHub Apps所需的权限”。

定义 GITHUB_TOKEN 权限的访问权限

您可以通过在 permissions 密钥中指定可用权限的值为 read、write 或 none 来定义 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 权限

此示例显示为 GITHUB_TOKEN 设置的权限，这些权限仅适用于名为 stale 的作业。为 issues 和 pull-requests 权限授予写入访问权限。所有其他权限将没有访问权限。

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5