octokit.js

Because you cannot expose a clientSecret in a browser, you must use a backend server running the App client to handle the OAuth flow.

1. The browser app initiates the flow and redirects the user to your server's /api/github/oauth/login.
2. After authorization, GitHub redirects to your server's /api/github/oauth/callback.
3. Your browser app must then capture the code and state from the URL parameters.
4. The browser app sends a POST request to your server's /api/github/oauth/token to exchange the code for an access token.
5. Use the resulting token to instantiate @octokit/core.

const code = new URL(location.href).searchParams.get("code");
if (code) {
  // remove ?code=... from URL
  const path =
    location.pathname +
    location.search.replace(/\b(code|state)=\\w+/g, "").replace(/[?&]+$/, "");
  history.replaceState({}, "", path);

  // exchange the code for a token with your backend.
  const response = await fetch("/api/github/oauth/token", {
    method: "POST",
    headers: {
      "content-type": "application/json",
    },
    body: JSON.stringify({ code }),
  });
  const { token } = await response.json();
  // `token` is the OAuth Access Token that can be use

  const { Octokit } = await import("https://esm.sh/@octokit/core");
  const octokit = new Octokit({ auth: token });

  const {
    data: {
      login,
    },
  } = await octokit.request("GET /user");
  alert("Hi there, " + login);
}

The App client provides app.webhooks.* APIs to receive, verify, and handle webhook events. You can define event listeners using app.webhooks.on(event_name, callback).

For Node.js servers, use createNodeMiddleware(app) to expose a webhook endpoint. For serverless environments, use app.webhooks.verifyAndReceive() to manually verify and process the event using headers and the request body.

import { createServer } from "node:http";
import { App, createNodeMiddleware } from "octokit";

const app = new App({
  appId,
  privateKey,
  webhooks: { secret },
});

// Handle a specific event
app.webhooks.on("issues.opened", ({ octokit, payload }) => {
  return octokit.rest.issues.createComment({
    owner: payload.repository.owner.login,
    repo: payload.repository.name,
    issue_number: payload.issue.number,
    body: "Hello, World!",
  });
});

// Expose the webhook endpoint via Node.js http server
createServer(createNodeMiddleware(app)).listen(3000);

// --- Serverless usage ---
// await app.webhooks.verifyAndReceive({
//   id: request.headers["x-github-delivery"],
//   name: request.headers["x-github-event"],
//   signature: request.headers["x-hub-signature-256"],
//   payload: request.body,
// });

The App client simplifies working with GitHub Apps by managing authentication (JWT and installation access tokens), webhooks, and OAuth. You can use it to iterate through all repositories an app is installed on or to get an octokit instance authenticated as a specific installation.

To use it, provide your appId and privateKey to the App constructor.

import { App } from "octokit";

const app = new App({ appId, privateKey });

// Example: Iterate through every repository the app is installed on
for await (const { octokit, repository } of app.eachRepository.iterator()) {
  await octokit.rest.repos.createDispatchEvent({
    owner: repository.owner.login,
    repo: repository.name,
    event_type: "my_event",
    client_payload: {
      foo: "bar",
    },
  });
  console.log("Event dispatched for %s", repository.full_name);
}

// Example: Get an octokit instance authenticated as a specific installation
const octokit = await app.getInstallationOctokit(123);

The App client supports OAuth for GitHub Apps. You can handle the OAuth web flow by providing clientId and clientSecret in the oauth configuration.

Key tasks include:

• Listening for token.created events.
• Exchanging a code for a token using app.oauth.createToken({ code }) (useful for serverless).
• Using the device flow with app.oauth.createToken({ async onVerification(verification) { ... } }).

Note: If you are building an OAuth App (not a GitHub App), use the @octokit/oauth-app package instead.

import { createServer } from "node:http";
import { App, createNodeMiddleware } from "octokit";

const app = new App({
  oauth: { clientId, clientSecret },
});

// Listen for successful token creation
app.oauth.on("token.created", async ({ token, octokit }) => {
  await octokit.rest.activity.setRepoSubscription({
    owner: "octocat",
    repo: "hello-world",
    subscribed: true,
  });
});

// Serverless: Exchange code for token
// const { token } = await app.oauth.createToken({ code: request.query.code });

createServer(createNodeMiddleware(app)).listen(3000);

When instantiating Octokit, you can provide several configuration options:

Common Options

• userAgent (String): Recommended to set your own user agent. It will be prepended to the default Octokit user agent.
• authStrategy (Function): The strategy used for authentication. Defaults to @octokit/auth-token.
• auth (String | Object): The authentication credentials (e.g., a personal access token) unless a custom authStrategy is used.
• baseUrl (String): Use this when connecting to GitHub Enterprise Server (e.g., https://github.acme-inc.com/api/v3).

Advanced Options

• request (Object):
  • request.signal: An AbortController instance to cancel requests.
  • request.fetch: A replacement for the built-in fetch method.
  • request.timeout (Node.js only): Sets a request timeout in milliseconds (defaults to 0).
• timeZone (String): Sets the Time-Zone header (using Olson database names) for generating commit timestamps.
• throttle (Object): Configures request throttling via @octokit/plugin-throttling. You can provide onRateLimit and onSecondaryRateLimit handlers. Set enabled: false to opt-out.
• retry (Object): Configures request retries via @octokit/plugin-retry. Set enabled: false to opt-out.