app.js

GitHub App toolset for Node.js

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

Usage

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

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", response.data.name);

for await (const { octokit, repository } of app.eachRepository.iterator()) {
  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(getNodeMiddleware(app)).listen(3000);
// can now receive requests at /api/github/*

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).
oauth.defaultScopes	Array of strings	Sets the default scopes value for app.oauth.getAuthorizationUrl(options). See available scopes

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.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 and ?scopes query parameters. ?scopes is a comma-separated list of supported OAuth scope names
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.

getNodeMiddleware(app, options)

Native http server middleware for Node.js

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

const middleware = getNodeMiddleware(app);

require("http").createServer(middleware).listen(3000);
// can now receive user authorization callbacks at /api/github/*

name	type	description
app	App instance	Required.
options.pathPrefix	string	All exposed paths will be prefixed with the provided prefix. Defaults to "/api/github"
options.onUnhandledRequest	function	Defaults to function onUnhandledRequest(request, response) { response.writeHead(400, { "content-type": "application/json", }); response.end( JSON.stringify({ error: error.message, }) ); }

Contributing

See CONTRIBUTING.md

License

MIT