core.js

Extendable client for GitHub's REST & GraphQL APIs

<!-- toc -->

• Usage
  • REST API example
  • GraphQL example
• Options
• Defaults
• Authentication
• Logging
• Hooks
• Plugins
• Build your own Octokit with Plugins and Defaults
• LICENSE

<!-- tocstop -->

If you need a minimalistic library to utilize GitHub's REST API and GraphQL API which you can extend with plugins as needed, then @octokit/core is a great starting point.

If you don't need the Plugin API then using @octokit/request or @octokit/graphql directly is a good alternative.

Usage

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

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

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

Install with <code>npm install @octokit/core</code>

import { Octokit } from "@octokit/core";

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

As we use conditional exports, you will need to adapt your tsconfig.json. See the TypeScript docs on package.json "exports".

REST API example

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

const response = await octokit.request("GET /orgs/{org}/repos", {
  org: "octokit",
  type: "private",
});

See @octokit/request for full documentation of the .request method.

GraphQL example

const octokit = new Octokit({ auth: `secret123` });

const response = await octokit.graphql(
  `query ($login: String!) {
    organization(login: $login) {
      repositories(privacy: PRIVATE) {
        totalCount
      }
    }
  }`,
  { login: "octokit" },
);

See @octokit/graphql for full documentation of the .graphql method.

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>options.authStrategy</code> </th> <td> <code>Function<code> </td> <td> Defaults to <a href="https://github.com/octokit/auth-token.js#readme"><code>@octokit/auth-token</code></a>. See <a href="#authentication">Authentication</a> below for examples. </td> </tr> <tr> <th> <code>options.auth</code> </th> <td> <code>String</code> or <code>Object</code> </td> <td> See <a href="#authentication">Authentication</a> below for examples. </td> </tr> <tr> <th> <code>options.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> <tr> <th> <code>options.previews</code> </th> <td> <code>Array of Strings</code> </td> <td>

Some REST API endpoints require preview headers to be set, or enable additional features. Preview headers can be set on a per-request basis, e.g.

octokit.request("POST /repos/{owner}/{repo}/pulls", {
  mediaType: {
    previews: ["shadow-cat"],
  },
  owner,
  repo,
  title: "My pull request",
  base: "main",
  head: "my-feature",
  draft: true,
});

You can also set previews globally, by setting the options.previews option on the constructor. Example:

const octokit = new Octokit({
  previews: ["shadow-cat"],
});

</td></tr> <tr> <th> <code>options.request</code> </th> <td> <code>Object</code> </td> <td>

Set a default request timeout (options.request.timeout) or an http(s).Agent e.g. for proxy usage (Node only, options.request.agent).

There are more options.request.* options, see @octokit/request options. options.request can also be set on a per-request basis.

</td></tr> <tr> <th> <code>options.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>options.userAgent</code> </th> <td> <code>String</code> </td> <td>

A custom user agent string for your app or library. Example

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

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

Defaults

You can create a new Octokit class with customized default options.

const MyOctokit = Octokit.defaults({
  auth: "personal-access-token123",
  baseUrl: "https://github.acme-inc.com/api/v3",
  userAgent: "my-app/v1.2.3",
});
const octokit1 = new MyOctokit();
const octokit2 = new MyOctokit();

If you pass additional options to your new constructor, the options will be merged shallowly.

const MyOctokit = Octokit.defaults({
  foo: {
    opt1: 1,
  },
});
const octokit = new MyOctokit({
  foo: {
    opt2: 1,
  },
});
// options will be { foo: { opt2: 1 }}

If you need a deep or conditional merge, you can pass a function instead.

const MyOctokit = Octokit.defaults((options) => {
  return {
    foo: Object.assign({}, options.foo, { opt1: 1 }),
  };
});
const octokit = new MyOctokit({
  foo: { opt2: 1 },
});
// options will be { foo: { opt1: 1, opt2: 1 }}

Be careful about mutating the options object in the Octokit.defaults callback, as it can have unforeseen consequences.

Authentication

Authentication is optional for some REST API endpoints accessing public data, but is required for GraphQL queries. Using authentication also increases your API rate limit.

By default, Octokit authenticates using the token authentication strategy. Pass in a token using options.auth. It can be a personal access token, an OAuth token, an installation access token or a JSON Web Token for GitHub App authentication. The Authorization header will be set according to the type of token.

import { Octokit } from "@octokit/core";

const octokit = new Octokit({
  auth: "mypersonalaccesstoken123",
});

const { data } = await octokit.request("/user");

To use a different authentication strategy, set options.authStrategy. A list of authentication strategies is available at octokit/authentication-strategies.js.

Example

import { Octokit } from "@octokit/core";
import { createAppAuth } from "@octokit/auth-app";

const appOctokit = new Octokit({
  authStrategy: createAppAuth,
  auth: {
    appId: 123,
    privateKey: process.env.PRIVATE_KEY,
  },
});

const { data } = await appOctokit.request("/app");

The .auth() method returned by the current authentication strategy can be accessed at octokit.auth(). Example

const { token } = await appOctokit.auth({
  type: "installation",
  installationId: 123,
});

Logging

There are four built-in log methods

1. octokit.log.debug(message[, additionalInfo])
2. octokit.log.info(message[, additionalInfo])
3. octokit.log.warn(message[, additionalInfo])
4. octokit.log.error(message[, additionalInfo])

They can be configured using the log client option. By default, octokit.log.debug() and octokit.log.info() are no-ops, while the other two call console.warn() and console.error() respectively.

This is useful if you build reusable plugins.

If you would like to make the log level configurable using an environment variable or external option, we recommend the console-log-level package. Example

import consoleLogLevel from "console-log-level";
const octokit = new Octokit({
  log: consoleLogLevel({ level: "info" }),
});

Hooks

You can customize Octokit's request lifecycle with hooks.

octokit.hook.before("request", async (options) => {
  validate(options);
});
octokit.hook.after("request", async (response, options) => {
  console.log(`${options.method} ${options.url}: ${response.status}`);
});
octokit.hook.error("request", async (error, options) => {
  if (error.status === 304) {
    return findInCache(error.response.headers.