octokit/rest.js

An Octokit plugin is a function with the following signature: const plugin = (octokit, options) => { ... }

Key Capabilities:

• Hook into the request lifecycle: Use octokit.hook.wrap(name, callback) to intercept and modify requests or responses. For example, wrapping "request" allows you to log timing or modify headers.
• Add custom methods: Return an object from the plugin function. The keys in this object become new methods available on the octokit instance.
• Access configuration: The second argument (options) is the configuration object passed to the constructor when the client is instantiated.

It is recommended to use octokit.log methods within plugins to assist users with debugging.

const plugin = (octokit, options = { greeting: "Hello" }) => {
  // 1. Hook into the request lifecycle
  octokit.hook.wrap("request", async (request, options) => {
    const time = Date.now();
    const response = await request(options);
    octokit.log.info(`${options.method} ${options.url} – ${response.status} in ${Date.now() - time}ms`);
    return response;
  });

  // 2. Add a custom method
  return {
    helloWorld: () => console.log(`${options.greeting}, world!`),
  };
};

export default plugin;

When you call a REST method, the final options used for the request are a result of merging three layers of configuration:

1. Global Defaults: Settings applied to all requests, such as baseUrl, user-agent, and accept headers, typically defined during new Octokit(options) initialization.
2. Endpoint Default Options: Hardcoded defaults for a specific API endpoint (e.g., the specific method and url template for repos.listForOrg).
3. User Options: The specific arguments you pass into the method call (e.g., { org: 'octokit' }).

Example: Calling octokit.rest.repos.listForOrg({ org: 'octokit', type: 'public' }) merges the global baseUrl, the endpoint's GET method and /orgs/{org}/repos URL, and your provided org and type parameters.

// Example of merging layers
// 1. Global: baseUrl: 'https://api.github.com'
// 2. Endpoint: method: 'GET', url: '/orgs/{org}/repos'
// 3. User: { org: 'octokit', type: 'public' }

// Resulting Endpoint Options:
// { baseUrl: 'https://api.github.com', method: 'GET', url: '/orgs/{org}/repos', org: 'octokit', type: 'public' }

// Resulting Request Options (after transformation):
// { method: 'GET', url: 'https://api.github.com/orgs/octokit/repos?type=public', ... }

octokit.rest.repos.listForOrg({ org: "octokit", type: "public" });

To use authentication strategies other than the default token strategy (such as OAuth Apps, GitHub Apps, or GitHub Actions), set the authStrategy option in the Octokit constructor to the strategy function, and provide the necessary credentials in the auth option.

Supported strategies include:

• @octokit/auth-token: Default strategy for personal access tokens.
• @octokit/auth-oauth-app: For OAuth Apps using client_id and client_secret or user access tokens.
• @octokit/auth-app: For GitHub Apps using installation access tokens or JWT.
• @octokit/auth-action: For GitHub Actions using the GITHUB_TOKEN secret.

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

const appOctokit = new Octokit({
  authStrategy: createAppAuth,
  auth: {
    appId: 123,
    privateKey: process.env.PRIVATE_KEY,
    // optional: this will make appOctokit authenticate as app (JWT)
    //           or installation (access token), depending on the request URL
    installationId: 123,
  },
});

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

Create an instance of the Octokit API by passing an options object to the Octokit constructor. While most options are optional, authentication is strongly encouraged.

Key configuration options include:

• auth: A personal access token string.
• userAgent: A string identifying your app or script (required by GitHub).
• previews: An array of API Preview headers to enable globally (e.g., ['jean-grey']).
• timeZone: A default time zone string (e.g., 'Europe/Amsterdam').
• baseUrl: Used for GitHub Enterprise instances.
• log: An object containing debug, info, warn, and error methods for custom logging.
• request: An object for custom request settings like agent, fetch, or timeout.

const octokit = new Octokit({
  auth: "secret123",
  userAgent: 'myApp v1.2.3',
  previews: ['jean-grey', 'symmetra'],
  timeZone: 'Europe/Amsterdam',
  baseUrl: 'https://api.github.com',
  log: {
    debug: () => {},
    info: () => {},
    warn: console.warn,
    error: console.error
  },
  request: {
    agent: undefined,
    fetch: undefined,
    timeout: 0
  }
});

You can customize and extend Octokit's functionality by using the Octokit.plugin() method. This method allows you to inject custom logic, such as request lifecycle hooks or new instance methods, into the Octokit client.

To use plugins:

1. Define a plugin function that accepts octokit as the first argument and an options object as the second.
2. The plugin function can return an object containing new methods to be added to the octokit instance.
3. Use Octokit.plugin(...plugins) to create a new constructor (e.g., MyOctokit) that includes the plugin logic.
4. Instantiate your new constructor with the desired configuration options.

import { Octokit } from "@octokit/rest";
import myPlugin from "./lib/my-plugin.js";

// Create a new constructor with the plugin applied
const MyOctokit = Octokit.plugin(myPlugin);

// Instantiate with options that will be passed to the plugin
const octokit = new MyOctokit({ greeting: "Hola" });

// Use methods added by the plugin
octokit.helloWorld();
// Output: Hola, world!