Skip to main content

使用 GitHub Actions 工作流中的 GitHub App 发出经过身份验证的 API 请求

可以使用 GitHub App 中的安装访问令牌在 GitHub Actions 工作流中发出经过身份验证的 API 请求。 还可以将令牌传递给自定义操作,使该操作能够发出经过身份验证的 API 请求。

关于 GitHub Actions 身份验证

如果需要在 GitHub Actions 工作流中发出经过身份验证的 API 请求,或者需要执行需要令牌的自定义操作,应尽可能使用内置 GITHUB_TOKEN。 但是,GITHUB_TOKEN 只能访问工作流存储库中的资源。 如果需要访问其他资源,例如组织或其他存储库中的资源,可以使用 GitHub App。 如需详细了解为什么优先使用 GitHub App 而不是 personal access token,请参阅“关于创建 GitHub 应用”。

使用 GitHub App 进行身份验证

若要使用 GitHub App 发出经过身份验证的 API 请求,必须注册 GitHub App,存储应用的凭据并安装应用。 完成此操作后,可以使用应用创建安装访问令牌,该令牌可用于在 GitHub Actions 工作流中发出经过身份验证的 API 请求。 还可以将安装访问令牌传递给需要令牌的自定义操作。

  1. 注册 GitHub App。 为 GitHub App 注册授予访问所需资源所需的权限。 有关详细信息,请参阅 注册 GitHub 应用为 GitHub Apps 选择权限

  2. 将 GitHub App 的应用 ID 存储为 GitHub Actions 配置变量。 可以在应用的设置页上找到应用 ID。 应用 ID 不同于客户端 ID。 若要详细了解如何导航到 GitHub App 的设置页,请参阅“修改 GitHub 应用注册”。 有关储存配置变量的详细信息,请参阅“在变量中存储信息”。

  3. 为应用生成私钥。 将所生成文件的内容作为机密进行存储。 (存储文件的全部内容,包括 -----BEGIN RSA PRIVATE KEY----------END RSA PRIVATE KEY-----。)有关详细信息,请参阅“管理 GitHub 应用的私钥”。 有关存储机密的详细信息,请参阅“在 GitHub Actions 中使用机密”。

  4. 在用户帐户或组织上安装 GitHub App,并向其授予对希望工作流访问的任何存储库的访问权限。 有关详细信息,请参阅“安装自己的 GitHub 应用”。

  5. 在 GitHub Actions 工作流中,创建可用于发出 API 请求的安装访问令牌。

为此,可以使用预制操作,如以下示例所示。 如果不想使用第三方操作,可以创建分支和修改 tibdex/github-app-token 操作,也可以编写脚本,使工作流手动创建安装令牌。 有关详细信息,请参阅“验证为 GitHub 应用程序安装”。

以下示例工作流使用 tibdex/github-app-token 操作生成安装访问令牌。 然后,工作流使用令牌通过 GitHub CLI 发出 API 请求。

在以下工作流中,将 APP_ID 替换为存储应用 ID 的配置变量的名称。 将 APP_PRIVATE_KEY 替换为存储应用私钥的机密的名称。

YAML

# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。

# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本,需要更新 SHA。
# 还可以引用标记或分支,但该操作可能会更改而不发出警告。

on:
  workflow_dispatch:
jobs:
  demo_app_authentication:
    runs-on: ubuntu-latest
    steps:
      - name: Generate a token
        id: generate-token
        uses: tibdex/github-app-token@32691ba7c9e7063bd457bd8f2a5703138591fa58 # v1.9.0
        with:
          app_id: ${{ vars.APP_ID }}
          private_key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Use the token
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api octocat