GitHub REST API 快速入门

简介

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

在命令行中使用 GitHub CLI

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

在 macOS、Windows 或 Linux 上安装 GitHub CLI。有关更多信息，请参阅 GitHub CLI 存储库中的安装。
通过从终端运行此命令来使用 GitHub 进行身份验证。
```
gh auth login
```
按照屏幕上的提示进行操作。

当您选择 HTTPS 作为 Git 操作的首选协议，并对询问您是否希望使用 GitHub 凭据对 Git 进行身份验证的提示回答“是”时，GitHub CLI 会自动为您存储 Git 凭据。这非常有用，因为它允许您使用 Git 命令（如 git push 和 git pull），而无需设置单独的凭据管理器或使用 SSH。
使用 GitHub CLI api 子命令（后跟路径）发出请求。使用 --method 或 -X 标志指定方法。有关更多信息，请参阅 GitHub CLI api 文档。

此示例向“获取 Octocat”端点发出请求，该端点使用 GET 方法和 /octocat 路径。有关此端点的完整参考文档，请参阅“元数据的 REST API 端点”。
Shell
```
gh api /octocat --method GET
```
```
gh api /octocat --method GET
```

在 GitHub Actions 中使用 GitHub CLI

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

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

以下示例工作流使用“列出存储库问题”端点，并请求 octocat/Spoon-Knife 存储库中的问题列表。

YAML

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

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

使用 GitHub 应用进行身份验证

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

将你的 GitHub 应用的 ID 存储为配置变量。在以下示例中，用配置变量的名称替换 APP_ID。你可以在应用的设置页面或通过 API 找到你的应用 ID。有关详细信息，请参阅“GitHub 应用的 REST API 端点”。有关配置变量的详细信息，请参阅“变量”。
为你的应用生成私钥。将生成的文件内容存储为机密。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，用机密的名称替换 APP_PEM。有关详细信息，请参阅“管理 GitHub 应用的私钥”。有关机密的详细信息，请参阅“在 GitHub Actions 中使用机密”。

添加一个步骤来生成令牌，并使用该令牌代替 GITHUB_TOKEN。请注意，此令牌将在 60 分钟后过期。例如

YAML

on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}
      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api https://api.github.com/repos/octocat/Spoon-Knife/issues


on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}
      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api https://api.github.com/repos/octocat/Spoon-Knife/issues

使用 Octokit.js

您可以在 JavaScript 脚本中使用 Octokit.js 与 GitHub REST API 进行交互。有关更多信息，请参阅“使用 REST API 和 JavaScript 进行脚本编写”。

创建一个访问令牌。例如，创建一个个人访问令牌或 GitHub 应用用户访问令牌。您将使用此令牌对您的请求进行身份验证，因此您应向其授予访问该端点所需的任何范围或权限。有关更多信息，请参阅“对 REST API 进行身份验证”或“识别和授权 GitHub 应用的用户”。

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

为了保护您的令牌安全，您可以将您的令牌存储为机密，并通过 GitHub Actions 运行您的脚本。有关更多信息，请参阅“在 GitHub Actions 中使用 Octokit.js”部分。

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

如果这些选项不可行，请考虑使用其他 CLI 服务来安全地存储您的令牌。
安装 octokit。例如，npm install octokit。有关安装或加载 octokit 的其他方法，请参阅 Octokit.js 自述文件。
在您的脚本中导入 octokit。例如，import { Octokit } from "octokit";。有关导入 octokit 的其他方法，请参阅 Octokit.js 自述文件。

使用您的令牌创建一个 Octokit 实例。将 YOUR-TOKEN 替换为您的令牌。

JavaScript

const octokit = new Octokit({ 
  auth: 'YOUR-TOKEN'
});

const octokit = new Octokit({ 
  auth: 'YOUR-TOKEN'
});

使用 octokit.request 来执行您的请求。将 HTTP 方法和路径作为第一个参数发送。在对象中将任何路径、查询和正文参数指定为第二个参数。有关参数的更多信息，请参阅“使用 REST API 入门”。

例如，在以下请求中，HTTP 方法为 GET，路径为 /repos/{owner}/{repo}/issues，参数为 owner: "octocat" 和 repo: "Spoon-Knife"。
JavaScript
```
await octokit.request("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 的更多信息，请参阅“自动令牌身份验证”。有关机密的更多信息，请参阅“在 GitHub Actions 中使用机密”。

以下示例工作流

签出存储库内容
设置 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@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        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 应用进行身份验证

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

将 GitHub 应用的 ID 存储为配置变量。在以下示例中，用 APP_ID 替换配置变量的名称。您可以在应用的设置页面或通过应用 API 找到您的应用 ID。有关更多信息，请参阅“GitHub 应用的 REST API 端点”。有关配置变量的更多信息，请参阅“变量”。
为你的应用生成私钥。将生成的文件内容存储为机密。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，用机密的名称替换 APP_PEM。有关详细信息，请参阅“管理 GitHub 应用的私钥”。有关机密的详细信息，请参阅“在 GitHub Actions 中使用机密”。

添加一个步骤来生成令牌，并使用该令牌代替 GITHUB_TOKEN。请注意，此令牌将在 60 分钟后过期。例如


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

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

      - name: Install dependencies
        run: npm install octokit

      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.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`

注意：如果您想从命令行发出 API 请求，GitHub 建议您使用 GitHub CLI，它简化了身份验证和请求。有关使用 GitHub CLI 入门 REST API 的更多信息，请参阅本文的 GitHub CLI 版本。

如果您的机器上尚未安装 curl，请安装 curl。要检查是否已安装 curl，请在命令行中执行 curl --version。如果输出提供了有关 curl 版本的信息，则表示已安装 curl。如果您收到类似于 command not found: curl 的消息，则需要下载并安装 curl。有关更多信息，请参阅curl 项目下载页面。
创建一个访问令牌。例如，创建一个个人访问令牌或 GitHub 应用用户访问令牌。您将使用此令牌对您的请求进行身份验证，因此您应授予它访问端点所需的任何范围或权限。有关更多信息，请参阅“对 REST API 进行身份验证”。

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

为了保护您的令牌的安全，您可以将您的令牌存储为 Codespaces 机密，并通过 Codespaces 使用命令行。有关更多信息，请参阅“管理 Codespaces 的加密机密”。

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

如果这些选项不可行，请考虑使用其他 CLI 服务来安全地存储您的令牌。

使用 curl 命令发出您的请求。在 Authorization 标头中传递您的令牌。将 YOUR-TOKEN 替换为您的令牌。

Shell

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer 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 命令。

使用访问令牌进行身份验证

YAML

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"

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 应用进行身份验证

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

将 GitHub 应用的 ID 存储为配置变量。在以下示例中，用 APP_ID 替换配置变量的名称。您可以在应用的设置页面或通过应用 API 找到您的应用 ID。有关更多信息，请参阅“GitHub 应用的 REST API 端点”。有关配置变量的更多信息，请参阅“变量”。
为您的应用生成私钥。将生成的文件内容存储为一个机密。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为机密的名称。有关详细信息，请参阅“管理 GitHub 应用的私钥”。有关存储机密的详细信息，请参阅“在 GitHub Actions 中使用机密”。

添加一个步骤来生成令牌，并使用该令牌代替 GITHUB_TOKEN。请注意，此令牌将在 60 分钟后过期。例如

YAML

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.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"


on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.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 Actions 中使用 GitHub CLI

使用访问令牌进行身份验证

使用 GitHub 应用进行身份验证

使用 Octokit.js

在 GitHub Actions 中使用 Octokit.js

使用访问令牌进行身份验证

使用 GitHub 应用进行身份验证

在命令行中使用 `curl`

在 GitHub Actions 中使用 `curl` 命令

使用访问令牌进行身份验证

使用 GitHub 应用进行身份验证

后续步骤