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

您可以在 JavaScript 脚本中使用 Octokit.js 与 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 App ID 存储为配置变量。在以下示例中，将APP_ID替换为配置变量的名称。您可以在应用的设置页面或通过 App API 找到您的 App ID。更多信息，请参阅“GitHub Apps 的 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 App 用户访问令牌。您将使用此令牌来验证您的请求，因此您应该为其提供访问端点所需的任何范围或权限。更多信息，请参阅“验证到 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 网络令牌 (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 API 找到您的 App 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:
  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 进行身份验证

后续步骤