Skip to main content

控制 GITHUB_TOKEN 的权限

修改授予 GITHUB_TOKEN 的默认权限。

注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

概述

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

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

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

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

权限允许操作使用 GITHUB_TOKEN
actions使用 GitHub Actions。 例如,actions: write 允许操作取消工作流运行。 有关详细信息,请参阅“GitHub 应用程序所需的权限”。

| checks | 使用检查运行和检查套件。 例如,checks: write 允许操作创建检查运行。 有关详细信息,请参阅“GitHub 应用程序所需的权限”。 | | contents | 处理存储库的内容。 例如,contents: read 允许操作列出提交,contents: write 允许操作创建发布。 有关详细信息,请参阅“GitHub 应用程序所需的权限”。 | | deployments | 处理部署。 例如,deployments: write 允许操作创建新部署。 有关详细信息,请参阅“GitHub 应用程序所需的权限”。 | | discussions | 使用 GitHub Discussions。 例如,discussions: write 允许操作关闭或删除讨论。 有关详细信息,请参阅“使用 GraphQL API for Discussions”。 | | 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 权限的访问权限

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

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|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-allwrite-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 权限

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

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5