GitHub REST API 快速入门

简介

本文介绍如何快速地通过 GitHub CLI、或 JavaScript 开始使用 GitHub REST API。有关更详细的指南，请参阅 AUTOTITLE。

在命令行中使用 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 CLI 将自动存储 Git 凭据，并对询问是否要使用 GitHub 凭据向 Git 进行身份验证的提示回答“是”。此操作非常有用，因为这允许直接使用 git push、git pull 等 Git 命令，无需设置单独的凭据管理器或使用 SSH。
使用 GitHub CLI 子命令发出请求，并在请求后附上路径。使用或标志指定方法。有关详细信息，请参阅 GitHub CLI 文档。

此示例向使用方法和路径的“Get Octocat”终结点发出请求。有关此终结点的完整参考文档，请参阅 AUTOTITLE。
Shell
```
gh api /octocat --method GET
```
```
gh api /octocat --method GET
```

在 GitHub Actions 中使用 GitHub CLI

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

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

不要使用命令，而是将访问令牌作为名为的环境变量进行传递。 GitHub 建议使用内置，而不是创建令牌。如果无法执行此操作，请将令牌存储为机密，并将以下示例中的替换为机密的名称。有关的详细信息，请参阅 AUTOTITLE。有关机密的详细信息，请参阅“AUTOTITLE”。

以下示例工作流使用“列出存储库问题”终结点，并请求你指定的存储库的问题列表。将替换为你的 GitHub Enterprise Server 实例的名称。请将替换为存储库所有者帐户的名称。请将替换为存储库的名称。

YAML

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

使用 GitHub App 进行身份验证

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

将 GitHub App 的 ID 存储为配置变量。在下面的示例中，将替换为配置变量的名称。可以在应用的设置页面上或通过 API 找到应用 ID。有关详细信息，请参阅“AUTOTITLE”。有关配置变量的详细信息，请参阅 AUTOTITLE。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括和。）在以下示例中，将替换为机密的名称。有关详细信息，请参阅“AUTOTITLE”。有关机密的详细信息，请参阅 AUTOTITLE。

添加用于生成令牌的步骤，并使用该令牌而不是。请注意，此令牌会在 60 分钟后过期。在以下示例中，将替换为你的 GitHub Enterprise Server 实例的名称。请将替换为存储库所有者帐户的名称。请将替换为存储库的名称。

YAML

on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v2
        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 http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v2
        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 http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

使用 Octokit.js

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

创建访问令牌。例如，创建 personal access token 或 GitHub App 用户访问令牌。你将使用此令牌对请求进行身份验证，因此应向其授予访问该终结点所需的任何范围或权限。有关详细信息，请参阅对 REST API 进行身份验证或 Identing and authorizing users for GitHub Apps。

警告

将访问令牌看做是密码。

若要确保令牌安全，可以将令牌存储为机密，并通过 GitHub Actions 运行脚本。有关详细信息，请参阅在 GitHub Actions 中使用 Octokit.js部分。

如果无法使用这些选项，请考虑使用其他 CLI 服务安全地存储令牌。
安装。例如，。有关安装或加载的其他方式，请参阅 Octokit.js 自述文件。
在脚本中导入。例如，。有关导入的其他方式，请参阅 Octokit.js 自述文件。

使用你的令牌创建实例。将替换为你的 GitHub Enterprise Server 实例的名称。将替换为你的令牌。

JavaScript

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN'
});

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN'
});

使用该工具执行请求。将 HTTP 方法和路径作为第一个参数发送。将对象中的任何路径、查询和正文参数指定为第二个参数。有关参数的详细信息，请参阅 AUTOTITLE。

例如，在以下请求中，HTTP 方法为，路径为，参数为以及。将替换为存储库拥有者帐户的名称，并将替换为存储库的名称。
JavaScript
```
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "REPO-OWNER",
  repo: "REPO-NAME",
});
```
```
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "REPO-OWNER",
  repo: "REPO-NAME",
});
```

在 GitHub Actions 中使用 Octokit.js

还可以在 GitHub Actions 工作流中执行 JavaScript 脚本。有关详细信息，请参阅“AUTOTITLE”。

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

GitHub 建议使用内置，而不是创建令牌。如果无法执行此操作，请将令牌存储为机密，并将以下示例中的替换为机密的名称。有关的详细信息，请参阅 AUTOTITLE。有关机密的详细信息，请参阅 AUTOTITLE。

以下示例工作流：

检出存储库内容
设置 Node.js
安装
将的值存储为名为的环境变量，并运行（它可以将该环境变量作为进行访问）

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

      - 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 }}

以下是一个包含文件路径的示例 JavaScript 脚本。请将文件路径替换为你的 GitHub Enterprise Server 实例的名称。请将替换为存储库所有者帐户的名称。请将替换为存储库的名称。

import { Octokit } from "octokit"

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "REPO-OWNER",
      repo: "REPO-NAME",
    });

  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 存储为配置变量。在下面的示例中，将替换为配置变量的名称。您可以在应用的设置页面上或通过应用 API 找到应用 ID。有关详细信息，请参阅“AUTOTITLE”。有关配置变量的详细信息，请参阅 AUTOTITLE。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括和。）在以下示例中，将替换为机密的名称。有关详细信息，请参阅“AUTOTITLE”。有关机密的详细信息，请参阅 AUTOTITLE。

添加用于生成令牌的步骤，并使用该令牌而不是。请注意，此令牌会在 60 分钟后过期。例如：

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

      - 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@v2
        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 }}

使用命令行中的

注意

如果要从命令行发出 API 请求，GitHub 建议使用 GitHub CLI，可以简化身份验证和请求。有关通过 GitHub CLI 开始使用 REST API 的详细信息，请参阅本文的 GitHub CLI 版本。

如果计算机上尚未安装，请安装。若要检查是否安装了，请在命令行中执行。如果输出信息包含有关<某软件>版本的信息，则表示<该软件>已安装。如果收到类似于的消息，则需要下载并安装。有关详细信息，请参阅 curl 项目下载页面。
创建访问令牌。例如，创建 personal access token 或 GitHub App 用户访问令牌。使用此令牌对请求进行身份验证，因此应向其授予访问终结点所需的任何范围或权限。有关详细信息，请参阅“AUTOTITLE”。

警告

将访问令牌看做是密码。

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

如果无法使用这些选项，请考虑使用其他 CLI 服务安全地存储令牌。
使用命令发出请求。在标头中传递你的令牌。将替换为你的 GitHub Enterprise Server 实例的名称。请将替换为存储库所有者帐户的名称。将替换为存储库的名称。将替换为令牌。
Shell
```
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
```
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
注意

在大多数情况下，可以使用 Authorization: Bearer 或 Authorization: token 传递令牌。但是，如果要传递 JSON Web 令牌 (JWT)，则必须使用 Authorization: Bearer。

在 GitHub Actions 中使用命令

还可以在 GitHub Actions 工作流中使用命令。

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

在以下示例中，将替换为你的 GitHub Enterprise Server 实例的名称。请将替换为存储库所有者帐户的名称。请将替换为存储库的名称。

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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

使用 GitHub App 进行身份验证

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

将 GitHub App 的 ID 存储为配置变量。在下面的示例中，将替换为配置变量的名称。您可以在应用的设置页面上或通过应用 API 找到应用 ID。有关详细信息，请参阅“AUTOTITLE”。有关配置变量的详细信息，请参阅 AUTOTITLE。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括和。）在以下示例中，将替换为机密的名称。有关详细信息，请参阅“AUTOTITLE”。有关存储机密的详细信息，请参阅 AUTOTITLE。

YAML

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v2
        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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/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@v2
        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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

后续步骤

有关更详细的指南，请参阅 REST API 入门。

Tool navigation

本文内容

简介

在命令行中使用 GitHub CLI

在 GitHub Actions 中使用 GitHub CLI

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

使用 GitHub App 进行身份验证

使用 Octokit.js

在 GitHub Actions 中使用 Octokit.js

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

使用 GitHub App 进行身份验证

使用命令行中的

在 GitHub Actions 中使用命令

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

使用 GitHub App 进行身份验证

后续步骤