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

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.

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.

All exposed paths will be prefixed with the provided prefix. Defaults to "/api/github"

Used for internal logging. Defaults to console with debug and info doing nothing.

  </td>
</tr>

Contributing

See CONTRIBUTING.md

License

MIT