在工作流程中使用 GITHUB_TOKEN

本教程将指导你如何在 GitHub Actions 工作流程中使用 GITHUB_TOKEN 进行身份验证，包括将令牌传递到操作、发出 API 请求以及配置权限以实现安全自动化的示例。

在工作流程中使用 `GITHUB_TOKEN`

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

重要

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

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

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

YAML

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` 的权限

在工作流程文件中使用 permissions 键来修改 GITHUB_TOKEN 对于整个工作流程或单个作业的权限。这允许您为工作流程或作业配置所需的最小权限。作为一种良好的安全做法，应授予 GITHUB_TOKEN 最低所需访问权限。

本文前面部分中的两个工作流程示例展示了在作业级别使用的 permissions 键。

授予额外权限

如果需要的令牌需要 GITHUB_TOKEN 中不可用的权限，请创建 GitHub App 并在工作流中生成安装访问令牌。有关详细信息，请参阅“使用 GitHub Actions 工作流中的 GitHub App 发出经过身份验证的 API 请求”。或者，可以创建 personal access token，将其作为机密存储在存储库中，并使用 ${{ secrets.SECRET_NAME }} 语法在工作流中使用令牌。有关详细信息，请参阅管理个人访问令牌和在 GitHub Actions 中使用机密。

在工作流程中使用 GITHUB_TOKEN

本文内容