关于 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 API 请求。
重要:即使工作流程没有明确将 GITHUB_TOKEN
传递到操作,操作也可以通过 github.token
上下文访问 GITHUB_TOKEN
。 作为一种良好的安全做法,应该始终通过限制授予 GITHUB_TOKEN
的权限,确保操作只有所需的最低访问权限。 有关详细信息,请参阅“GITHUB_TOKEN
的权限”。
使用存储库的 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 应用程序所需的权限”。
下表显示了默认授予 GITHUB_TOKEN
的权限。 对企业、组织或仓库、具有管理权限的人可以设置默认权限为允许或限制。 有关如何为企业、组织或存储库设置默认 GITHUB_TOKEN
权限的信息,请参阅“在企业中为 GitHub Actions 实施策略”、“禁用或限制组织的 GitHub Actions”或“管理存储库的 GitHub Actions 设置”。
范围 | 默认访问权限 (允许) | 默认访问权限 (限制) | 对来自公共分支 存储库的拉取请求 的最大访问权限 |
---|---|---|---|
actions | 读/写 | 无 | 读取 |
attestations | 读/写 | 无 | 读取 |
检查 | 读/写 | 无 | 读取 |
内容 | 读/写 | 读取 | 读取 |
deployments | 读/写 | 无 | 读取 |
讨论 | 读/写 | 无 | 读取 |
id-token | 无 | 无 | 无 |
issues | 读/写 | 无 | 读取 |
metadata | 读取 | 读取 | 读取 |
packages | 读/写 | 读取 | 读取 |
页 | 读/写 | 无 | 读取 |
pull-requests | 读/写 | 无 | 读取 |
repository-projects | 读/写 | 无 | 读取 |
security-events | 读/写 | 无 | 读取 |
statuses | 读/写 | 无 | 读取 |
注意:
- 当工作流由
pull_request_target
事件触发时,将授予GITHUB_TOKEN
读/写存储库权限,即使从公共分支触发也是如此。 有关详细信息,请参阅“触发工作流的事件”。 - 专用存储库可以控制来自分支的拉取请求是否可以运行工作流,以及是否可以配置分配给
GITHUB_TOKEN
的权限。 有关详细信息,请参阅“管理存储库的 GitHub Actions 设置”。 - Dependabot 拉取请求触发的工作流运行就像是来自存储库分支一样,因此使用只读
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
密钥,因为最佳做法是限制权限的范围。
有关 permissions
密钥的完整详细信息,请参阅“GitHub Actions 的工作流语法”。
注意: 组织 和企业所有者可以阻止你授予对 GITHUB_TOKEN
的存储库级别的写入访问权限。 有关更多信息,请参阅“禁用或限制组织的 GitHub Actions” 和“在企业中为 GitHub Actions 实施策略”。
如何计算工作流程作业的权限
GITHUB_TOKEN
的权限最初设置为企业、组织或存储库的默认设置。 如果默认设置为这些级别中任何级别的限制权限,这将适用于相关的仓库。 例如,如果您在组织级别选择受限制的默认值,则该组织中的所有仓库将使用限制的权限作为默认值。 然后根据工作流程文件中的任何配置(首先在工作流程级别,然后在作业级别)对权限进行调整。 最后,如果工作流程是由分叉的存储库中的拉取请求触发,并且未选择“Send write tokens to workflows from pull requests(将写入令牌从拉取请求发送到工作流程)”设置,则权限调整为将任何写入权限更改为只读。
授予额外权限
如果需要的令牌需要 GITHUB_TOKEN
中不可用的权限,则可以创建 GitHub App 并在工作流中生成安装访问令牌。 有关详细信息,请参阅“使用 GitHub Actions 工作流中的 GitHub App 发出经过身份验证的 API 请求”。 或者,可以创建 personal access token,将其作为机密存储在存储库中,并使用 ${{ secrets.SECRET_NAME }}
语法在工作流中使用令牌。 有关详细信息,请参阅“管理个人访问令牌”和“在 GitHub Actions 中使用机密”。