自动令牌身份验证

关于 `GITHUB_TOKEN` 密钥

在每个工作流作业开始时，GitHub 会自动创建一个唯一的 `GITHUB_TOKEN` 密钥供您在工作流中使用。您可以使用 `GITHUB_TOKEN` 在工作流作业中进行身份验证。

启用 GitHub Actions 后，GitHub 会在您的存储库中安装一个 GitHub 应用。`GITHUB_TOKEN` 密钥是 GitHub 应用安装访问令牌。您可以使用安装访问令牌代表安装在您的存储库上的 GitHub 应用进行身份验证。令牌的权限仅限于包含您的工作流的存储库。有关详细信息，请参阅“`GITHUB_TOKEN` 的权限”。

在每个作业开始之前，GitHub 会为该作业获取安装访问令牌。`GITHUB_TOKEN` 在作业完成或最多 24 小时后过期。

该令牌也位于 `github.token` 上下文中。有关详细信息，请参阅“访问有关工作流运行的上下文信息”。

在工作流中使用 `GITHUB_TOKEN`

您可以使用引用密钥的标准语法使用 `GITHUB_TOKEN`：`${{ secrets.GITHUB_TOKEN }}`。使用 `GITHUB_TOKEN` 的示例包括将令牌作为输入传递给操作，或使用它来发出经过身份验证的 GitHub API 请求。

当您使用仓库的GITHUB_TOKEN执行任务时，由GITHUB_TOKEN触发的事件（workflow_dispatch和repository_dispatch除外）不会创建新的工作流程运行。这可以防止您意外创建递归工作流程运行。例如，如果工作流程运行使用仓库的GITHUB_TOKEN推送代码，即使仓库包含在push事件发生时配置为运行的工作流程，也不会运行新的工作流程。

使用GITHUB_TOKEN的 GitHub Actions 工作流程推送的提交不会触发 GitHub Pages 构建。

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

此示例工作流程使用GitHub CLI，它需要GITHUB_TOKEN作为GH_TOKEN输入参数的值

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

示例 2：调用 REST API

您可以使用GITHUB_TOKEN进行身份验证的 API 调用。此示例工作流程使用 GitHub REST API 创建一个问题。

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    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 The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

GITHUB_TOKEN 的权限

有关 GitHub Apps 可以使用每种权限访问的 API 端点的信息，请参见“GitHub Apps所需的权限”。

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

修改GITHUB_TOKEN的权限

您可以在单个工作流程文件中修改GITHUB_TOKEN的权限。如果GITHUB_TOKEN的默认权限是严格的，您可能需要提升权限才能使某些操作和命令成功运行。如果默认权限是宽松的，您可以编辑工作流程文件以从GITHUB_TOKEN中删除某些权限。作为良好的安全实践，您应该向GITHUB_TOKEN授予最少的必需访问权限。

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

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

您可以使用permissions键添加和删除fork仓库的读取权限，但通常无法授予写入权限。此行为的例外情况是管理员用户已在 GitHub Actions 设置中选择了**将写入令牌发送到来自 pull requests 的工作流程**选项。更多信息，请参见“管理仓库的 GitHub Actions 设置”。

本文前面介绍的两个工作流程示例显示了在作业级别使用permissions键的情况，因为限制权限范围是最佳实践。

有关permissions键的完整详细信息，请参见“GitHub Actions 的工作流程语法”。

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

GITHUB_TOKEN的权限最初设置为企业、组织或仓库的默认设置。如果在任何这些级别将默认值设置为受限权限，则这将应用于相关仓库。例如，如果您在组织级别选择受限默认值，则该组织中的所有仓库都将使用受限权限作为默认值。然后根据工作流程文件中的任何配置调整权限，首先在工作流程级别，然后在作业级别。最后，如果工作流程是由来自fork仓库的pull request触发的，并且未选择**将写入令牌发送到来自pull requests 的工作流程**设置，则权限将被调整以将任何写入权限更改为只读。

授予其他权限

如果您需要一个需要GITHUB_TOKEN中不可用权限的令牌，您可以创建一个 GitHub App，并在您的工作流程中生成安装访问令牌。更多信息，请参见“在 GitHub Actions 工作流程中使用 GitHub App 进行身份验证的 API 请求”。或者，您可以创建一个个人访问令牌，将其存储为仓库中的密钥，并使用${{ secrets.SECRET_NAME }}语法在您的工作流程中使用该令牌。更多信息，请参见“管理您的个人访问令牌”和“在 GitHub Actions 中使用密钥”。

进一步阅读

• “REST API 的速率限制”