GitHub REST API 快速入门

本文介绍如何快速地通过 GitHub CLI、JavaScript 或 cURL 开始使用 GitHub REST API。有关更详细的指南，请参阅“REST API 入门”。

开始使用 GitHub CLI

在命令行中使用 GitHub CLI

GitHub CLI 是从命令行使用 GitHub REST API 的最简单方式。

如果尚未安装 GitHub CLI，请进行安装。有关安装说明，请参阅 GitHub CLI 存储库。
使用 auth login 子命令向 GitHub CLI 进行身份验证。有关详细信息，请参阅 GitHub CLI auth login 文档。
```
gh auth login
```
使用 api 子命令发出 API 请求。有关详细信息，请参阅 GitHub CLI api 文档。
```
gh api repos/octocat/Spoon-Knife/issues
```

在 GitHub Actions 中使用 GitHub CLI

还可以在 GitHub Actions 工作流中使用 GitHub CLI。有关详细信息，请参阅“在工作流中使用 GitHub CLI”。

不要使用 gh auth login 命令，而是将访问令牌作为名为 GH_TOKEN 的环境变量进行传递。 GitHub 建议使用内置 GITHUB_TOKEN，而不是创建令牌。如果无法执行此操作，请将令牌存储为机密，并将以下示例中的 GITHUB_TOKEN 替换为机密的名称。有关 GITHUB_TOKEN 的详细信息，请参阅“自动令牌身份验证”。有关机密的详细信息，请参阅“已加密的机密”。

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api repos/octocat/Spoon-Knife/issues

如果使用 GitHub App 进行身份验证，则可以在工作流中创建安装访问令牌：

将 GitHub App 的 ID 作为机密进行存储。在以下示例中，将 APP_ID 替换为机密的名称。可以在应用的设置页面上或通过 API 找到应用 ID。有关详细信息，请参阅 REST API 文档中的“应用”。有关机密的详细信息，请参阅“已加密的机密”。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为机密的名称。有关详细信息，请参阅“使用 GitHub Apps 进行身份验证”。
添加用于生成令牌的步骤，并使用该令牌而不是 GITHUB_TOKEN。请注意，此令牌会在 60 分钟后过期。例如：

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

on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.APP_PEM }}

      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
        run: |
          gh api repos/octocat/Spoon-Knife/issues

开始使用 JavaScript

可以在 JavaScript 脚本中使用 Octokit.js 与 GitHub REST API 进行交互。有关详细信息，请参阅 Octokit.js 自述文件。

使用 Octokit.js

创建访问令牌。例如，创建 personal access token 或 GitHub App 用户到服务器访问令牌。有关详细信息，请参阅“创建 personal access token”或“识别和授权 GitHub 应用的用户”。

警告：将访问令牌视为密码。

若要确保令牌安全，可以将令牌存储为机密，并通过 GitHub Actions 运行脚本。有关详细信息，请参阅“在 GitHub Actions 中使用 Octokit.js”部分。

还可以将令牌存储为 Codespaces 机密，并在 Codespaces 中运行脚本。有关详细信息，请参阅“管理 codespace 的加密机密。”

如果无法使用这些选项，请考虑使用其他服务（如 1Password CLI）安全地存储令牌。
安装 octokit。例如，npm install octokit。有关安装或加载 octokit 的其他方式，请参阅 Octokit.js 自述文件。
在脚本中导入 octokit。例如，import { Octokit } from "octokit";。有关导入 octokit 的其他方式，请参阅 Octokit.js 自述文件。
使用密钥创建 Octokit 的实例。将 YOUR-TOKEN 替换为你的令牌。
```
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
});
```
使用 octokit.request 执行请求。将 HTTP 方法和路径作为第一个参数发送。将对象中的任何路径、查询和正文参数指定为第二个参数。例如，在以下请求中，HTTP 方法为 GET，路径为 /repos/{owner}/{repo}/issues，参数为 owner: "octocat" 和 repo: "Spoon-Knife"。
```
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
});
```

在 GitHub Actions 中使用 Octokit.js

还可以在 GitHub Actions 工作流中执行 JavaScript 脚本。有关详细信息，请参阅“GitHub Actions 的工作流语法”。

GitHub 建议使用内置 GITHUB_TOKEN，而不是创建令牌。如果无法执行此操作，请将令牌存储为机密，并将以下示例中的 GITHUB_TOKEN 替换为机密的名称。有关 GITHUB_TOKEN 的详细信息，请参阅“自动令牌身份验证”。有关机密的详细信息，请参阅“已加密的机密”。

以下示例工作流：

签出存储库内容
设置 Node.js
安装 octokit
将 GITHUB_TOKEN 的值存储为名为 TOKEN 的环境变量，并运行 .github/actions-scripts/use-the-api.mjs（它可以将该环境变量作为 process.env.TOKEN 进行访问）。

示例工作流：

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - name: Check out repo content
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        run: |
          node .github/actions-scripts/use-the-api.mjs
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}

文件路径为 .github/actions-scripts/use-the-api.mjs 的示例 JavaScript 脚本：

import { Octokit } from "octokit"

const octokit = new Octokit({
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "octocat",
      repo: "Spoon-Knife",
    });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

如果使用 GitHub App 进行身份验证，则可以在工作流中创建安装访问令牌：

将 GitHub App 的 ID 作为机密进行存储。在以下示例中，将 APP_ID 替换为机密的名称。您可以在应用的设置页面上或通过应用 API 找到应用 ID。有关详细信息，请参阅“应用”。有关机密的详细信息，请参阅“已加密的机密”。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为机密的名称。有关详细信息，请参阅“使用 GitHub Apps 进行身份验证”。
添加用于生成令牌的步骤，并使用该令牌而不是 GITHUB_TOKEN。请注意，此令牌会在 60 分钟后过期。例如：

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

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repo content
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.APP_PEM }}

      - name: Run script
        run: |
          node .github/actions-scripts/use-the-api.mjs
        env:
          TOKEN: ${{ steps.generate_token.outputs.token }}

开始使用 cURL

在命令行中使用 cURL

注意：如果要从命令行发出 API 请求，GitHub 建议使用 GitHub CLI，这可简化身份验证和请求。有关通过 GitHub CLI 开始使用 REST API 的详细信息，请参阅本文的 GitHub CLI 版本。

如果计算机上尚未安装 cURL，请安装 cURL。若要检查是否安装了 cURL，请在命令行中执行 curl --version。如果输出是有关 cURL 版本的信息，则 cURL 已安装。如果收到类似于 command not found: curl 的消息，则需要下载并安装 cURL。有关详细信息，请参阅 cURL 项目下载页面。
创建访问令牌。例如，创建 personal access token 或 GitHub App 用户到服务器访问令牌。有关详细信息，请参阅“创建 personal access token”或“识别和授权 GitHub 应用的用户”。

警告：将访问令牌视为密码。

若要确保令牌安全，可以将令牌存储为 Codespaces 机密，并通过 Codespaces 使用命令行。有关详细信息，请参阅“管理 codespace 的加密机密。”

还可以使用 GitHub CLI，而不是 cURL。 GitHub CLI 会为你处理身份验证。有关详细信息，请参阅此页面的 GitHub CLI 版本。

如果无法使用这些选项，请考虑使用其他服务（如 1Password CLI）安全地存储令牌。
使用 cURL 命令发出请求。在 Authorization 标头中传递令牌。将 YOUR-TOKEN 替换为你的令牌。
```
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
注意：在大多数情况下，可以使用 Authorization: Bearer 或 Authorization: token 传递令牌。但是，如果要传递 JSON Web 令牌 (JWT)，则必须使用 Authorization: Bearer。

在 GitHub Actions 中使用 cURL

还可以在 GitHub Actions 工作流中使用 cURL。

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

如果使用 GitHub App 进行身份验证，则可以在工作流中创建安装访问令牌：

将 GitHub App 的 ID 作为机密进行存储。在以下示例中，将 APP_ID 替换为机密的名称。您可以在应用的设置页面上或通过应用 API 找到应用 ID。有关详细信息，请参阅“应用”。有关机密的详细信息，请参阅“已加密的机密”。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为机密的名称。有关详细信息，请参阅“使用 GitHub Apps 进行身份验证”。
添加用于生成令牌的步骤，并使用该令牌而不是 GITHUB_TOKEN。请注意，此令牌会在 60 分钟后过期。例如：

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

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.APP_PEM }}

      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
        run: |
          curl --request GET \
          --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

后续步骤

有关更详细的指南，请参阅“REST API 入门”。

GitHub REST API 快速入门

本文内容

开始使用 GitHub CLI

在命令行中使用 GitHub CLI

在 GitHub Actions 中使用 GitHub CLI

开始使用 JavaScript

使用 Octokit.js

在 GitHub Actions 中使用 Octokit.js

开始使用 cURL

在命令行中使用 cURL

在 GitHub Actions 中使用 cURL

后续步骤