Skip to main content

自动令牌身份验证

GitHub 提供一个令牌,可用于代表 GitHub Actions 进行身份验证。

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

关于 GITHUB_TOKEN 机密

在每个工作流程运行开始时,GitHub 会自动创建唯一的 GITHUB_TOKEN 机密以在工作流程中使用。 可以使用 GITHUB_TOKEN 在工作流程运行中进行身份验证。

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

在每个作业开始之前, GitHub 将为作业提取安装访问令牌。 GITHUB_TOKEN 在作业完成或最多 24 小时后过期。

令牌在 github.token 上下文中也可用。 有关详细信息,请参阅“上下文”。

在工作流程中使用 GITHUB_TOKEN

可以使用标准语法引用密钥以使用 GITHUB_TOKEN${{ secrets.GITHUB_TOKEN }}GITHUB_TOKEN 的使用示例包括将令牌作为某个操作的输入来传递,或使用它来发出经验证的 GitHub Enterprise Server API 请求。

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

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

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

此示例工作流程使用 labeler 操作,该操作需要 GITHUB_TOKEN 作为 repo-token 输入参数的值:

YAML
name: Pull request labeler
on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v4
        with:
          repo-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 http(s)://HOSTNAME/api/v3/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 App 权限”。

下表显示了默认授予 GITHUB_TOKEN 的权限。 对组织或仓库具有管理权限的人可以设置默认权限为允许或限制。 有关如何为企业、组织或存储库设置 GITHUB_TOKEN 的默认权限的信息,请参阅“在企业强制实施 GitHub Actions 的策略”、“为组织禁用或限制 GitHub Actions”或“管理存储库的 GitHub Actions 设置。”

范围默认访问权限
(允许)
默认访问权限
(限制)
对来自公共分支
存储库的拉取请求
的最大访问权限[†]
actions读/写读取
检查读/写读取
内容读/写读取读取
deployments读/写读取
issues读/写读取
metadata读取读取读取
packages读/写读取
读/写读取
pull-requests读/写读取
repository-projects读/写读取
security-events读/写读取
statuses读/写读取

[†] 专用存储库可以控制来自分支的拉取请求是否可以运行工作流,并配置分配给 GITHUB_TOKEN 的权限。 有关详细信息,请参阅“管理存储库的 GitHub Actions 设置”。

修改 GITHUB_TOKEN 的权限

可在单个工作流文件中修改 GITHUB_TOKEN 的权限。 如果 GITHUB_TOKEN 的默认权限受限,可能需要提升权限以允许一些操作和命令成功运行。 如果默认权限是非限制性的,你可以编辑工作流文件以从 GITHUB_TOKEN 中删除部分权限。 作为一种不错的安全做法,应授予 GITHUB_TOKEN 最少的访问权限。

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

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

可以使用 permissions 密钥添加和删除分叉存储库的读取权限,但通常不能授予其写入权限。 此行为的例外情况是,管理员用户已在 GitHub Actions 设置中选择了“通过拉取请求向工作流发送写入令牌”选项。 有关详细信息,请参阅“管理存储库的 GitHub Actions 设置”。

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

有关 permissions 密钥的完整详细信息,请参阅“GitHub Actions 的工作流程语法”。

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

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

授予额外权限

如果你需要的令牌需要 GITHUB_TOKEN 中未提供的权限,可以创建personal access token并将其设置为存储库中的机密:

  1. 使用或创建具有该仓库适当权限的令牌。 有关详细信息,请参阅“创建personal access token”。
  2. 添加令牌作为工作流程存储库中的机密,然后使用 ${{ secrets.SECRET_NAME }} 语法进行引用。 有关详细信息,请参阅“创建和使用已加密的机密”。

延伸阅读