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

• 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

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

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

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

import { Octokit, App } from "octokit";

[!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".

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

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

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

Advanced options

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

{
  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;
    }
  },
};

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

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

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 on request URLs
const {
  data: { slug },
} = await octokit.rest.apps.getAuthenticated();

// creates an installation access token as needed
// assumes that installationId 123 belongs to @octocat, otherwise the request will fail
await octokit.rest.issues.create({
  owner: "octocat",
  repo: "hello-world",
  title: "Hello world from " + slug,
});

You can use the App or OAuthApp SDKs which provide APIs and internal wiring to cover most use cases.

For example, to implement the above using App

const app = new App({ appId, privateKey });
const { data: slug } = await app.octokit.rest.apps.getAuthenticated();
const octokit = await app.getInstallationOctokit(123);
await octokit.rest.issues.create({
  owner: "octocat",
  repo: "hello-world",
  title: "Hello world from " + slug,
});

Learn more about how authentication strategies work or how to create your own.

Proxy Servers (Node.js only)

By default, the Octokit API client does not make use of the standard proxy server environment variables. To add support for proxy servers you will need to provide an https client that supports them such as undici.ProxyAgent().

For example, this would use a ProxyAgent to make requests through a proxy server:

import { fetch as undiciFetch, ProxyAgent } from 'undici';

const myFetch = (url, options) => {
  return undiciFetch(url, {
    ...options,
    dispatcher: new ProxyAgent(<your_proxy_url>)
  })
}

const octokit = new Octokit({
  request: {
     fetch: myFetch
  },
});

If you are writing a module that uses Octokit and is designed to be used by other people, you should ensure that consumers can provide an alternative agent for your Octokit or as a parameter to specific calls such as:

import { fetch as undiciFetch, ProxyAgent } from 'undici';

const myFetch = (url, options) => {
  return undiciFetch(url, {
    ...options,
    dispatcher: new ProxyAgent(<your_proxy_url>)
  })
}

octokit.rest.repos.get({
  owner,
  repo,
  request: {
    fetch: myFetch
  },
});

Fetch missing

If you get the following error:

fetch is not set. Please pass a fetch implementation as new Octokit({ request: { fetch }}).

It probably means you are trying to run Octokit with an unsupported version of NodeJS. Octokit requires Node 18 or higher, which includes a native fetch API.

To bypass this problem you can provide your own fetch implementation (or a built-in version like node-fetch) like this:

import fetch from "node-fetch";

const octokit = new Octokit({
  request: {
    fetch: fetch,
  },
});

REST API

There are two ways of using the GitHub REST API, the octokit.rest.* endpoint methods and octokit.request. Both act the same way, the octokit.rest.* methods are just added for convenience, they use octokit.request internally.

For example

await octokit.rest.issues.create({
  owner: "octocat",
  repo: "hello-world",
  title: "Hello, world!",
  body: "I created this issue using Octokit!",
});

Is the same as

await octokit.request("POST /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "hello-world",
  title: "Hello, world!",
  body: "I created this issue using Octokit!",
});

In both cases a given request is authenticated, retried, and throttled transparently by the octokit instance which also manages the accept and user-agent headers as needed.

octokit.request can be used to send requests to other domains by passing a full URL and to send requests to endpoints that are not (yet) documented in [GitHub's REST API doc