# 在工作流中使用 GITHUB_TOKEN 进行身份验证

了解如何使用 GITHUB_TOKEN 以 GitHub Actions 的身份进行身份验证。

本教程介绍如何在 `GITHUB_TOKEN` 工作流中使用 GitHub Actions 身份验证，包括将令牌传递给操作、发出 API 请求和配置安全自动化权限的示例。

有关参考信息，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#permissions)。

## 在工作流程中使用 `GITHUB_TOKEN`

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

> \[!IMPORTANT]
> 即使工作流没有明确将 `GITHUB_TOKEN` 传递到操作，操作也可以通过 `github.token` 上下文访问 `GITHUB_TOKEN`。 作为一种良好的安全做法，应该始终通过限制授予 `GITHUB_TOKEN` 的权限，确保操作只有所需的最低访问权限。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#permissions)”。

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

此示例工作流程使用 [GitHub CLI](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-github-cli)，该方式需要 `GITHUB_TOKEN` 作为 `GH_TOKEN` 输入参数的值：

```yaml copy
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 创建问题：

```yaml
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` 最低所需访问权限。

若要查看可使用权限的列表及其参数化名称，请参阅 [管理个人访问令牌](/zh/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#account-permissions)。

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

## 授予额外权限

如果您需要的令牌要求具备 `GITHUB_TOKEN` 中未提供的权限，请创建一个 GitHub App，并在工作流中生成安装访问令牌。 有关详细信息，请参阅“[在GitHub Actions工作流中使用GitHub应用发出经过身份验证的 API 请求](/zh/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)”。 或者，您可以创建一个 personal access token，将其作为机密存储在仓库中，并在工作流中使用该令牌，语法为 `${{ secrets.SECRET_NAME }}`。 有关详细信息，请参阅 [管理个人访问令牌](/zh/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 和 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。

## 后续步骤

* [GITHUB\_TOKEN](/zh/actions/concepts/security/github_token)
* [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#permissions)