core.js

Extendable client for GitHub's REST & GraphQL APIs

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

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

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

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

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

REST API example

1// Create a personal access token at https://github.com/settings/tokens/new?scopes=repo
2const octokit = new Octokit({ auth: `personal-access-token123` });
3
4const response = await octokit.request("GET /orgs/{org}/repos", {
5  org: "octokit",
6  type: "private",
7});

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

GraphQL example

1const octokit = new Octokit({ auth: `secret123` });
2
3const response = await octokit.graphql(
4  `query ($login: String!) {
5    organization(login: $login) {
6      repositories(privacy: PRIVATE) {
7        totalCount
8      }
9    }
10  }`,
11  { login: "octokit" },
12);

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

Options

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

1octokit.request("POST /repos/{owner}/{repo}/pulls", {
2  mediaType: {
3    previews: ["shadow-cat"],
4  },
5  owner,
6  repo,
7  title: "My pull request",
8  base: "main",
9  head: "my-feature",
10  draft: true,
11});

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

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

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

Defaults

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

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

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

1const MyOctokit = Octokit.defaults({
2  foo: {
3    opt1: 1,
4  },
5});
6const octokit = new MyOctokit({
7  foo: {
8    opt2: 1,
9  },
10});
11// options will be { foo: { opt2: 1 }}

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

1const MyOctokit = Octokit.defaults((options) => {
2  return {
3    foo: Object.assign({}, options.foo, { opt1: 1 }),
4  };
5});
6const octokit = new MyOctokit({
7  foo: { opt2: 1 },
8});
9// 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.

1import { Octokit } from "@octokit/core";
2
3const octokit = new Octokit({
4  auth: "mypersonalaccesstoken123",
5});
6
7const { 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

1import { Octokit } from "@octokit/core";
2import { createAppAuth } from "@octokit/auth-app";
3
4const appOctokit = new Octokit({
5  authStrategy: createAppAuth,
6  auth: {
7    appId: 123,
8    privateKey: process.env.PRIVATE_KEY,
9  },
10});
11
12const { data } = await appOctokit.request("/app");

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

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

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

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

Hooks

You can customize Octokit's request lifecycle with hooks.

1octokit.hook.before("request", async (options) => {
2  validate(options);
3});
4octokit.hook.after("request", async (response, options) => {
5  console.log(`${options.method} ${options.url}: ${response.status}`);
6});
7octokit.hook.error("request", async (error, options) => {
8  if (error.status === 304) {
9    return findInCache(error.response.headers.etag);
10  }
11
12  throw error;
13});
14octokit.hook.wrap("request", async (request, options) => {
15  // add logic before, after, catch errors or replace the request altogether
16  return request(options);
17});

See before-after-hook for more documentation on hooks.

Plugins

Octokit’s functionality can be extended using plugins. The Octokit.plugin() method accepts a plugin (or many) and returns a new constructor.

A plugin is a function which gets two arguments:

1. the current instance
2. the options passed to the constructor.

In order to extend octokit's API, the plugin must return an object with the new methods. Please refrain from adding methods directly to the octokit instance, especialy if you depend on keys that do not exist in @octokit/core, such as octokit.rest.

1// index.js
2import { Octokit } from "@octokit/core";
3import myPlugin from "./lib/my-plugin.js";
4import octokitPluginExample from "octokit-plugin-example";
5const MyOctokit = Octokit.plugin(
6  myPlugin,
7  octokitPluginExample
8);
9
10const octokit = new MyOctokit({ greeting: "Moin moin" });
11octokit.helloWorld(); // logs "Moin moin, world!"
12octokit.request("GET /"); // logs "GET / - 200 in 123ms"
13
14// lib/my-plugin.js
15const plugin = (octokit, options = { greeting: "Hello" }) => {
16  // hook into the request lifecycle
17  octokit.hook.wrap("request", async (request, options) => {
18    const time = Date.now();
19    const response = await request(options);
20    console.log(
21      `${options.method} ${options.url} – ${response.status} in ${Date.now() -
22        time}ms`
23    );
24    return response;
25  });
26
27  // add a custom method
28  return {
29    helloWorld: () => console.log(`${options.greeting}, world!`);
30  }
31};
32export default plugin;

Build your own Octokit with Plugins and Defaults

You can build your own Octokit class with preset default options and plugins. In fact, this is mostly how the @octokit/<context> modules work, such as @octokit/action:

1import { Octokit } from "@octokit/core";
2import { paginateRest } from "@octokit/plugin-paginate-rest";
3import { throttling } from "@octokit/plugin-throttling";
4import { retry } from "@octokit/plugin-retry";
5import { createActionAuth } from "@octokit/auth-action";
6const MyActionOctokit = Octokit.plugin(
7  paginateRest,
8  throttling,
9  retry,
10).defaults({
11  throttle: {
12    onAbuseLimit: (retryAfter, options) => {
13      /* ... */
14    },
15    onRateLimit: (retryAfter, options) => {
16      /* ... */
17    },
18  },
19  authStrategy: createActionAuth,
20  userAgent: `my-octokit-action/v1.2.3`,
21});
22
23const octokit = new MyActionOctokit();
24const installations = await octokit.paginate("GET /app/installations");

LICENSE

MIT