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 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 应用程序的私钥”。有关秘密的更多信息，请参阅“在 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 应用程序用户访问令牌。您将使用此令牌来验证您的请求，因此您应该赋予它访问该端点所需的任何范围或权限。有关更多信息，请参阅“验证 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 App 进行身份验证

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

将你的 GitHub App 的 ID 存储为一个配置变量。在以下示例中，将 APP_ID 替换为配置变量的名称。你可以在你的 App 的设置页面或通过 App API 找到你的 App ID。有关更多信息，请参阅“GitHub Apps 的 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 --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 App 的 ID 存储为一个配置变量。在以下示例中，将 APP_ID 替换为配置变量的名称。你可以在你的 App 的设置页面或通过 App API 找到你的 App ID。有关更多信息，请参阅“GitHub Apps 的 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 App 进行身份验证

使用 Octokit.js

在 GitHub Actions 中使用 Octokit.js

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

使用 GitHub App 进行身份验证

在命令行中使用 `curl`

在 GitHub Actions 中使用 `curl` 命令

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

使用 GitHub App 进行身份验证

下一步