octokit.js

The all-batteries-included GitHub SDK for Browsers, Node.js, and Deno.

The octokit package integrates the three main Octokit libraries

1. API client (REST API requests, GraphQL API queries, Authentication)
2. App client (GitHub App & installations, Webhooks, OAuth)
3. Action client (Pre-authenticated API client for single repository)

Table of contents <!-- omit in toc -->

<!-- toc -->

• octokit.js
  • Features
  • Usage
  • Octokit API Client
    • Constructor options
    • Authentication
    • Proxy Servers (Node.js only)
      • Fetch missing
    • REST API
      • octokit.rest endpoint methods
      • octokit.request()
      • Pagination
      • Media Type formats
      • Request error handling
    • GraphQL API queries
      • Pagination
      • Schema previews
  • App client
    • GitHub App
    • Webhooks
    • OAuth
    • App Server
    • OAuth for browser apps
  • Action client
  • LICENSE

<!-- tocstop -->

Features

• Complete. All features of GitHub's platform APIs are covered.
• Prescriptive. All recommended best practices are implemented.
• Universal. Works in all modern browsers, Node.js, and Deno.
• Tested. All libraries have a 100% test coverage.
• Typed. All libraries have extensive TypeScript declarations.
• Decomposable. Use only the code you need. You can build your own Octokit in only a few lines of code or use the underlying static methods. Make your own tradeoff between functionality and bundle size.
• Extendable. A feature missing? Add functionalities with plugins, hook into the request or webhook lifecycle or implement your own authentication strategy.

Usage

<table> <tbody valign=top align=left> <tr><th> Browsers </th><td width=100%> Load <code>octokit</code> directly from <a href="https://esm.sh">esm.sh</a>

<script type="module">
import { Octokit, App } from "https://esm.sh/octokit";
</script>

</td></tr> <tr><th> Deno </th><td width=100%> Load <code>octokit</code> directly from <a href="https://esm.sh">esm.sh</a>

import { Octokit, App } from "https://esm.sh/octokit?dts";

</td></tr> <tr><th> Node </th><td>

Install with <code>npm/pnpm install octokit</code>, or <code>yarn add octokit</code>

import { Octokit, App } from "octokit";

</td></tr> </tbody> </table>

[!IMPORTANT] As we use conditional exports, you will need to adapt your tsconfig.json by setting "moduleResolution": "node16", "module": "node16".

See the TypeScript docs on package.json "exports".<br> See this helpful guide on transitioning to ESM from @sindresorhus

Octokit API Client

standalone minimal Octokit: @octokit/core.

The Octokit client can be used to send requests to GitHub's REST API and queries to GitHub's GraphQL API.

Example: Get the username for the authenticated user.

// Create a personal access token at https://github.com/settings/tokens/new?scopes=repo
const octokit = new Octokit({ auth: `personal-access-token123` });

// Compare: https://docs.github.com/en/rest/reference/users#get-the-authenticated-user
const {
  data: { login },
} = await octokit.rest.users.getAuthenticated();
console.log("Hello, %s", login);

Constructor options

The most commonly used options are

<table> <thead align=left> <tr> <th> name </th> <th> type </th> <th width=100%> description </th> </tr> </thead> <tbody align=left valign=top> <tr> <th> <code>userAgent</code> </th> <td> <code>String</code> </td> <td>

Setting a user agent is required for all requests sent to GitHub's Platform APIs. The user agent defaults to something like this: octokit.js/v1.2.3 Node.js/v8.9.4 (macOS High Sierra; x64). It is recommend to set your own user agent, which will prepend the default one.

const octokit = new Octokit({
  userAgent: "my-app/v1.2.3",
});

</td> </tr> <tr> <th> <code>authStrategy</code> </th> <td> <code>Function</code> </td> <td>

Defaults to @octokit/auth-token.

See Authentication below.

</td> </tr> <tr> <th> <code>auth</code> </th> <td> <code>String</code> or <code>Object</code> </td> <td>

Set to a personal access token unless you changed the authStrategy option.

See Authentication below.

</td> </tr> <tr> <th> <code>baseUrl</code> </th> <td> <code>String</code> </td> <td>

When using with GitHub Enterprise Server, set options.baseUrl to the root URL of the API. For example, if your GitHub Enterprise Server's hostname is github.acme-inc.com, then set options.baseUrl to https://github.acme-inc.com/api/v3. Example

const octokit = new Octokit({
  baseUrl: "https://github.acme-inc.com/api/v3",
});

</td> </tr> </tbody> </table>

Advanced options

<table> <thead align=left> <tr> <th> name </th> <th> type </th> <th width=100%> description </th> </tr> </thead> <tbody align=left valign=top> <tr> <th> <code>request</code> </th> <td> <code>Object</code> </td> <td>

• request.signal: Use an AbortController instance to cancel a request. abort-controller is an implementation for Node.
• request.fetch: Replacement for built-in fetch method.

Node only

• request.timeout sets a request timeout, defaults to 0

The request option can also be set on a per-request basis.

</td></tr> <tr> <th> <code>timeZone</code> </th> <td> <code>String</code> </td> <td>

Sets the Time-Zone header which defines a timezone according to the list of names from the Olson database.

const octokit = new Octokit({
  timeZone: "America/Los_Angeles",
});

The time zone header will determine the timezone used for generating the timestamp when creating commits. See GitHub's Timezones documentation.

</td> </tr> <tr> <th> <code>throttle</code> </th> <td> <code>Object</code> </td> <td>

Octokit implements request throttling using @octokit/plugin-throttling

By default, requests are retried once and warnings are logged in case of hitting a rate or secondary rate limit.

{
  onRateLimit: (retryAfter, options, octokit) => {
    octokit.log.warn(
      `Request quota exhausted for request ${options.method} ${options.url}`
    );

    if (options.request.retryCount === 0) {
      // only retries once
      octokit.log.info(`Retrying after ${retryAfter} seconds!`);
      return true;
    }
  },
  onSecondaryRateLimit: (retryAfter, options, octokit) => {
    octokit.log.warn(
      `SecondaryRateLimit detected for request ${options.method} ${options.url}`
    );

    if (options.request.retryCount === 0) {
      // only retries once
      octokit.log.info(`Retrying after ${retryAfter} seconds!`);
      return true;
    }
  },
};

To opt-out of this feature:

new Octokit({ throttle: { enabled: false } });

Throttling in a cluster is supported using a Redis backend. See @octokit/plugin-throttling Clustering

</td> </tr> <tr> <th> <code>retry</code> </th> <td> <code>Object</code> </td> <td>

Octokit implements request retries using @octokit/plugin-retry

To opt-out of this feature:

new Octokit({ retry: { enabled: false } });

</td> </tr> </tbody> </table>

Authentication

By default, the Octokit API client supports authentication using a static token.

There are different means of authentication that are supported by GitHub, that are described in detail at octokit/authentication-strategies.js. You can set each of them as the authStrategy constructor option, and pass the strategy options as the auth constructor option.

For example, in order to authenticate as a GitHub App Installation:

import { createAppAuth } from "@octokit/auth-app";
const octokit = new Octokit({
  authStrategy: createAppAuth,
  auth: {
    appId: 1,
    privateKey: "-----BEGIN PRIVATE KEY-----\n...",
    installationId: 123,
  },
});

// authenticates as app based