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 替换为配置变量的名称。您可以在您的 App 的设置页面或通过 API 找到您的 App ID。有关更多信息，请参阅“GitHub Apps 的 REST API 端点”。有关配置变量的更多信息，请参阅“在变量中存储信息”。
为您的 App 生成私钥。将结果文件的全部内容存储为机密。（存储文件的全部内容，包括 -----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设置页面或通过App API找到你的App ID。有关更多信息，请参阅“GitHub Apps的REST API端点”。有关配置变量的更多信息，请参阅“存储信息到变量中”。
为您的 App 生成私钥。将结果文件的全部内容存储为机密。（存储文件的全部内容，包括 -----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 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端点”。有关配置变量的更多信息，请参阅“存储信息到变量中”。
为你的App生成一个私钥。将结果文件的内容存储为一个密钥。（存储文件的全部内容，包括-----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 进行身份验证

后续步骤