@octokit/app

What is @octokit/app?

@octokit/app is a Node.js library for GitHub Apps to authenticate as an app or as an installation. It provides methods to create and verify JSON Web Tokens (JWT) for app authentication and to create installation access tokens.

What are @octokit/app's main functionalities?

Creating a JSON Web Token (JWT)

This feature allows you to create a JWT for your GitHub App. The JWT is used to authenticate as the app itself.

const { App } = require('@octokit/app');
const app = new App({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY
});
const jwt = app.getSignedJsonWebToken();
console.log(jwt);

Creating an installation access token

This feature allows you to create an installation access token, which is used to authenticate as an installation of the app.

const { App } = require('@octokit/app');
const app = new App({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY
});
const installationAccessToken = await app.getInstallationAccessToken({ installationId: 123 });
console.log(installationAccessToken);

Verifying a webhook event

This feature allows you to verify the signature of a webhook event to ensure it came from GitHub.

const { App } = require('@octokit/app');
const app = new App({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  webhooks: {
    secret: process.env.WEBHOOK_SECRET
  }
});
const isValid = app.webhooks.verify(eventPayload, signature);
console.log(isValid);

Other packages similar to @octokit/app

probot

Probot is a framework for building GitHub Apps to automate and improve your workflow. It provides higher-level abstractions and a more opinionated structure compared to @octokit/app, making it easier to get started with building GitHub Apps.

github-app

github-app is a lightweight library for creating GitHub App tokens. It focuses on simplicity and minimalism, providing only the essential features needed for authentication, unlike @octokit/app which offers a more comprehensive set of tools.

README

app.js

GitHub App toolset for Node.js

• Usage
• App.defaults(options)
• Constructor
• API
  • app.octokit
  • app.log
  • app.getInstallationOctokit
  • app.eachInstallation
  • app.eachRepository
  • app.getInstallationUrl
  • app.webhooks
  • app.oauth
• Middlewares
  • createNodeMiddleware(app, options)
• Contributing
• License

Usage

Browsers	@octokit/app is not meant for browser usage.
Node	Install with npm install @octokit/app const { App, createNodeMiddleware } = require("@octokit/app");

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

const app = new App({
  appId: 123,
  privateKey: "-----BEGIN PRIVATE KEY-----\n...",
  oauth: {
    clientId: "0123",
    clientSecret: "0123secret",
  },
  webhooks: {
    secret: "secret",
  },
});

const { data } = await app.octokit.request("/app");
console.log("authenticated as %s", data.name);
for await (const { installation } of app.eachInstallation.iterator()) {
  for await (const { octokit, repository } of app.eachRepository.iterator({
    installationId: installation.id,
  })) {
    await octokit.request("POST /repos/{owner}/{repo}/dispatches", {
      owner: repository.owner.login,
      repo: repository.name,
      event_type: "my_event",
    });
  }
}

app.webhooks.on("issues.opened", async ({ octokit, payload }) => {
  await octokit.request(
    "POST /repos/{owner}/{repo}/issues/{issue_number}/comments",
    {
      owner: payload.repository.owner.login,
      repo: payload.repository.name,
      issue_number: payload.issue.number,
      body: "Hello World!",
    },
  );
});

app.oauth.on("token", async ({ token, octokit }) => {
  const { data } = await octokit.request("GET /user");
  console.log(`Token retrieved for ${data.login}`);
});

require("http").createServer(createNodeMiddleware(app)).listen(3000);
// can now receive requests at /api/github/*

App.defaults(options)

Create a new App with custom defaults for the constructor options

const MyApp = App.defaults({
  Octokit: MyOctokit,
});
const app = new MyApp({ clientId, clientSecret });
// app.octokit is now an instance of MyOctokit

Constructor

name	type	description
appId	number	Required. Find the App ID on the app’s about page in settings.
privateKey	string	Required. Content of the *.pem file you downloaded from the app’s about page. You can generate a new private key if needed.
Octokit	Constructor	You can pass in your own Octokit constructor with custom defaults and plugins. Note that authStrategy will be always be set to createAppAuth from @octokit/auth-app. For usage with enterprise, set baseUrl to the hostname + /api/v3. Example: const { Octokit } = require("@octokit/core"); new App({ appId: 123, privateKey: "-----BEGIN PRIVATE KEY-----\n...", oauth: { clientId: 123, clientSecret: "secret", }, webhooks: { secret: "secret", }, Octokit: Octokit.defaults({ baseUrl: "https://ghe.my-company.com/api/v3", }), }); Defaults to @octokit/core.
log	object	Used for internal logging. Defaults to console.
webhooks.secret	string	Required. Secret as configured in the GitHub App's settings.
webhooks.transform	function	Only relevant for `app.webhooks.on`. Transform emitted event before calling handlers. Can be asynchronous.
oauth.clientId	number	Find the OAuth Client ID on the app’s about page in settings.
oauth.clientSecret	number	Find the OAuth Client Secret on the app’s about page in settings.
oauth.allowSignup	boolean	Sets the default value for app.oauth.getAuthorizationUrl(options).

API

app.octokit

Octokit instance. Uses the Octokit constructor option if passed.

app.log

See https://github.com/octokit/core.js#logging. Customize using the log constructor option.

app.getInstallationOctokit

const octokit = await app.getInstallationOctokit(123);

app.eachInstallation

for await (const { octokit, installation } of app.eachInstallation.iterator()) { /* ... */ }
await app.eachInstallation(({ octokit, installation }) => /* ... */)

app.eachRepository

for await (const { octokit, repository } of app.eachRepository.iterator()) { /* ... */ }
await app.eachRepository(({ octokit, repository }) => /* ... */)

Optionally pass installation ID to iterate through all repositories in one installation

for await (const { octokit, repository } of app.eachRepository.iterator({ installationId })) { /* ... */ }
await app.eachRepository({ installationId }, ({ octokit, repository }) => /* ... */)

app.getInstallationUrl

const installationUrl = await app.getInstallationUrl();
return res.redirect(installationUrl);

Optionally pass the ID of a GitHub organization or user to request installation on that specific target.

If the user will be sent to a redirect URL after installation (such as if you request user authorization during installation), you can also supply a state string that will be included in the query of the post-install redirect.

const installationUrl = await app.getInstallationUrl({ state, target_id });
return res.redirect(installationUrl);

app.webhooks

An @octokit/webhooks instance

app.oauth

An @octokit/oauth-app instance

Middlewares

A middleware is a method or set of methods to handle requests for common environments.

By default, all middlewares expose the following routes

Route	Route Description
POST /api/github/webhooks	Endpoint to receive GitHub Webhook Event requests
GET /api/github/oauth/login	Redirects to GitHub's authorization endpoint. Accepts optional ?state query parameter.
GET /api/github/oauth/callback	The client's redirect endpoint. This is where the token event gets triggered
POST /api/github/oauth/token	Exchange an authorization code for an OAuth Access token. If successful, the token event gets triggered.
GET /api/github/oauth/token	Check if token is valid. Must authenticate using token in Authorization header. Uses GitHub's POST /applications/{client_id}/token endpoint
PATCH /api/github/oauth/token	Resets a token (invalidates current one, returns new token). Must authenticate using token in Authorization header. Uses GitHub's PATCH /applications/{client_id}/token endpoint.
DELETE /api/github/oauth/token	Invalidates current token, basically the equivalent of a logout. Must authenticate using token in Authorization header.
DELETE /api/github/oauth/grant	Revokes the user's grant, basically the equivalent of an uninstall. must authenticate using token in Authorization header.

createNodeMiddleware(app, options)

Middleware for Node's built in http server or express.

const { App, createNodeMiddleware } = require("@octokit/app");

const app = new App({
  appId: 123,
  privateKey: "-----BEGIN PRIVATE KEY-----\n...",
  oauth: {
    clientId: "0123",
    clientSecret: "0123secret",
  },
  webhooks: {
    secret: "secret",
  },
});

const middleware = createNodeMiddleware(app);
require("http")
  .createServer(async (req, res) => {
    // `middleware` returns `false` when `req` is unhandled (beyond `/api/github`)
    if (await middleware(req, res)) return;
    res.writeHead(404);
    res.end();
  })
  .listen(3000);
// can now receive user authorization callbacks at /api/github/*

The middleware returned from createNodeMiddleware can also serve as an Express.js middleware directly.

name	type	description
app	App instance	Required.
options.pathPrefix	string	All exposed paths will be prefixed with the provided prefix. Defaults to "/api/github"
log object	Used for internal logging. Defaults to console with debug and info doing nothing. </td> </tr>

Contributing

See CONTRIBUTING.md

License

MIT