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
```
选择您要进行身份验证的位置
- 如果您访问 GitHub.com 上的 GitHub，请选择**GitHub.com**。
- 如果您在不同的域名访问 GitHub，请选择**其他**，然后输入您的主机名（例如：`octocorp.ghe.com`）。
按照屏幕上的其余提示操作。

当您选择 HTTPS 作为 Git 操作的首选协议并回答“是”以确认您是否要使用您的 GitHub 凭据对 Git 进行身份验证时，GitHub CLI 会自动为您存储您的 Git 凭据。这非常有用，因为它允许您使用诸如 `git push` 和 `git pull` 之类的 Git 命令，而无需设置单独的凭据管理器或使用 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 Actions 工作流中使用 GitHub CLI。有关更多信息，请参阅“在工作流中使用 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 App 进行身份验证

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

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

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

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

警告

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

为确保令牌安全，您可以将令牌存储为机密，然后通过 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 App 进行身份验证

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

将您的 GitHub 应用 ID 存储为配置变量。在以下示例中，将APP_ID替换为配置变量的名称。您可以在应用的设置页面或通过应用 API 找到您的应用 ID。更多信息，请参阅“GitHub 应用的 REST API 端点”。有关配置变量的更多信息，请参阅“在变量中存储信息”。
为您的应用生成私钥。将结果文件的全部内容存储为机密。（存储文件的全部内容，包括 `-----BEGIN RSA PRIVATE KEY-----` 和 `-----END RSA PRIVATE KEY-----`。）在以下示例中，将 `APP_PEM` 替换为机密的名称。有关更多信息，请参阅“管理 GitHub Apps 的私钥”。有关机密的更多信息，请参阅“在 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 --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 App 进行身份验证

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

将您的 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 CLI

在 GitHub Actions 中使用 GitHub CLI

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

使用 GitHub App 进行身份验证

使用 Octokit.js

在 GitHub Actions 中使用 Octokit.js

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

使用 GitHub App 进行身份验证

在命令行中使用`curl`

在 GitHub Actions 中使用`curl`命令

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

使用 GitHub App 进行身份验证

后续步骤