JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1258632
  • Score
    100M100P100Q191172F
  • License MIT

GitHub Apps toolset for Node.js

Package Exports

  • @octokit/app

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@octokit/app) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

app.js

GitHub App toolset for Node.js

@latest Build Status

Usage

Browsers

@octokit/app is not meant for browser usage.

Node

Install with npm install @octokit/app

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 { data } = await app.octokit.request("/app");
console.log("authenticated as %s", 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(createNodeMiddleware(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).

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 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)

Native http server middleware for Node.js

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(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