工作流程中的身份验证

关于 `GITHUB_TOKEN` 密码

GitHub 会自动创建 GITHUB_TOKEN 密码以在工作流程中使用。您可以使用 GITHUB_TOKEN 在工作流程运行中进行身份验证。

当您启用 GitHub Actions 时，GitHub 在您的仓库中安装 GitHub 应用程序。 GITHUB_TOKEN 密码是一种 GitHub 应用程序安装访问令牌。您可以使用安装访问令牌代表仓库中安装的 GitHub 应用程序进行身份验证。令牌的权限仅限于包含您的工作流程的仓库。更多信息请参阅“GITHUB_TOKEN 的权限”。

在每个作业开始之前， GitHub 将为作业提取安装访问令牌。令牌在作业完成后过期。

令牌在 github.token 上下文中也可用。更多信息请参阅“GitHub Actions 的上下文和表达式语法”。

在工作流程中使用 `GITHUB_TOKEN`

您可以使用标准语法引用密钥以使用 GITHUB_TOKEN：${{ secrets.GITHUB_TOKEN }}。使用 GITHUB_TOKEN 的示例包括将令牌作为操作的输入，或使用它来建立验证的 GitHub API 请求。

重要：即使工作流程没有明确将 GITHUB_TOKEN 传递到操作，操作也可以通过 github.token 上下文访问 GITHUB_TOKEN 。作为一种良好的安全做法，您应该始终通过限制授予 GITHUB_TOKEN 的权限，确保操作只有所需的最低访问权限。更多信息请参阅“GITHUB_TOKEN 的权限”。

使用仓库的 GITHUB_TOKEN 代表 GitHub Actions 应用程序执行任务时，GITHUB_TOKEN 触发的事件不会创建新的工作流程运行。这可以防止意外创建递归工作流程运行。例如，如果工作流程运行使用仓库的 GITHUB_TOKEN 推送代码，则即使仓库包含配置为在 push 事件发生时运行的工作流程，新工作流程也不会运行。

示例 1：将 `GITHUB_TOKEN` 作为输入传递

此示例工作流程使用贴标器操作，需要 GITHUB_TOKEN 作为 repo-token 输入参数的值：

name: Pull request labeler

on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v2
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

例2：调用 REST API

您可以使用 GITHUB_TOKEN 进行经过验证的 API 调用。此示例工作流程使用 GitHub REST API 创建议题：

name: Create issue on commit

on: [ push ]

jobs:
  create_commit:
    runs-on: ubuntu-latest 
    permissions:
      issues: write 
    steps:
      - name: Create issue using REST API
        run: 
          curl --request POST \
          --url https://api.github.com/repos/${{ github.repository }}/issues \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ github.sha }}",
            "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n 提交哈希是： _${{ github.sha }}_"
            }' \
          --fail

`GITHUB_TOKEN` 的权限

有关 GitHub 应用程序可通过各种权限访问的 API 端点的信息，请参阅“GitHub 应用程序权限”。

下表显示默认情况下授予 GITHUB_TOKEN 的权限。拥有企业、组织或仓库管理员权限的人员可以将默认权限设置为允许或限制。有关如何为您的企业、组织或仓库设置 GITHUB_TOKEN 的默认权限的信息，请参阅“在企业帐户中执行 GitHub Actions 策略”、“禁用或限制组织的 GitHub Actions”或“禁用或限制仓库的 GitHub Actions”。

作用域	默认访问（允许）	默认访问（限制）	复刻的仓库的最大访问权限
操作	读/写	无	读取
检查	读/写	无	读取
内容	读/写	读取	读取
部署	读/写	无	读取
议题	读/写	无	读取
元数据	读取	读取	读取
包	读/写	无	读取
拉取请求	读/写	无	读取
仓库项目	读/写	无	读取
安全事件	读/写	无	读取
状态	读/写	无	读取

注意： 由 Dependabot 拉取请求触发的工作流程运行就像是来自复刻的仓库一样，并因此使用只读 GITHUB_TOKEN。这些工作流程运行无法访问任何密钥。请参阅“确保 GitHub Actions 和工作流程安全：阻止 pwn 请求”，了解确保这些工作流程安全的策略。

修改 `GITHUB_TOKEN` 的权限

您可以在个别工作流程文件中修改 GITHUB_TOKENN 的权限。如果 GITHUB_TOKEN 的默认权限是限制的，您可能需要提高权限以允许一些操作和命令成功运行。如果默认权限是允许的，您可以编辑工作流程文件以从 GITHUB_TOKEN 中删除某些权限。作为一种良好的安全做法，您应该授予 GITHUB_TOKEN 所需的最小访问权限。

您可以在工作流程运行日志的“设置作业”部分看到 GITHUB_TOKEN 对于特定作业的权限。更多信息请参阅“使用工作流程运行日志”。

您可以在工作流文件中使用 permissions 键来修改 GITHUB_TOKEN 对于整个工作流或单个作业的权限。这允许您为工作流程或作业配置所需的最小权限。使用 permissions 键时，所有未指定的权限都设置为没有访问权限，metadata范围除外，该范围总是获得读取访问。

您可以使用 permissions 键来添加和删除复刻仓库的读取权限，但通常不能授予写入权限。此行为的例外情况是，管理员在 GitHub Actions 设置中选择了 Send write tokens to workflows from pull requests（从拉取请求发送写入令牌到工作流程）选项。更多信息请参阅“禁用或限制仓库的 GitHub Actions”。

本文前面的两个工作流程示例显示了在工作流程级别和作业级别使用的 permissions 键。在例 1 中，为整个工作流程指定了两个权限。在示例 2 中，为单个作业的单一范围授予写入访问权限。

有关 permissions 键的完整详情，请参阅“GitHub Actions 的工作流程语法”。

如何计算工作流程作业的权限

GITHUB_TOKEN 的权限最初设置为企业、组织或仓库的默认设置。如果默认设置为这些级别中任何级别的限制权限，这将适用于相关的仓库。例如，如果您在组织级别选择受限制的默认值，则该组织中的所有仓库将使用限制的权限作为默认值。然后根据工作流程文件中的任何配置（首先在工作流程级别，然后在作业级别）对权限进行调整。最后，如果工作流程是由复刻的仓库中的拉取请求触发，并且未选择从拉取请求发送写入令牌到工作流程设置，则权限调整为将任何写入权限更改为只读。

授予额外权限

如果您需要的令牌需要 GITHUB_TOKEN 中未提供的权限，您可以创建个人访问令牌并将其设置为仓库中的密码：

使用或创建具有该仓库适当权限的令牌。更多信息请参阅“创建个人访问令牌”。
添加令牌作为工作流程仓库中的密码，然后使用 ${{ secrets.SECRET_NAME }} 语法进行引用。更多信息请参阅“创建和使用加密密码”。

按产品浏览