本教程将指导你如何在 GitHub Actions 工作流程中使用 GITHUB_TOKEN
进行身份验证,包括将令牌传递到操作、发出 API 请求以及配置权限以实现安全自动化的示例。
有关参考信息,请参阅 GitHub Actions 的工作流语法。
在工作流程中使用 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
输入参数的值:
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 中使用机密。