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

⚠️ Deprecated

@octokit/app is being deprecated in favor of @octokit/auth-app. The @octokit/app package will be repurposed, starting with version 10.0.0.

See usage examples for @octokit/auth-app below the examples for @octokit/app.

app.js

GitHub App Authentication client for JavaScript

@octokit/app has methods to receive tokens for a GitHub app and its installations. The tokens can then be used to interact with GitHub’s REST API or GraphQL API. Note that @octokit/app does not have methods to send any requests, you will need to use your own request library such as @octokit/request. Alternatively you can use the octokit package which comes with everything you need to integrate with any of GitHub’s APIs.

Usage

Browsers	Load `@octokit/app` directly from unpkg.com <script type="module"> import { App } from "https://unpkg.com/@octokit/app"; </script>
Node	Install with `npm install @octokit/app` const { App } = require("@octokit/app"); // or: import { App } from "@octokit/app";

Authenticating as an App

In order to authenticate as a GitHub App, you need to generate a Private Key and use it to sign a JSON Web Token (jwt) and encode it. See also the GitHub Developer Docs.

Here is how the code looks like with the deprecated @octokit/app package.

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

const app = new App({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
});
const jwt = app.getSignedJsonWebToken();

To achive the same with @octokit/auth-app, do the following

const { createAppAuth } = require("@octokit/auth-app");
const { request } = require("@octokit/request");

const auth = createAppAuth({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
});
auth({ type: "app" }).then((authentication) => {
  const jwt = authentication.token;
});

Authenticating as an Installation

Once you have authenticated as a GitHub App, you can use that in order to request an installation access token. Calling requestToken() automatically performs the app authentication for you. See also the GitHub Developer Docs.

Here is how the code looks like with the deprecated @octokit/app package.

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

const APP_ID = 1; // replace with your app ID
const PRIVATE_KEY = "-----BEGIN RSA PRIVATE KEY-----\n..."; // replace with contents of your private key. Replace line breaks with \n

const app = new App({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY
});
await app.getInstallationAccessToken({
  installationId: process.env.INSTALLATION_ID
}).then(installationAccessToken => {
  // https://developer.github.com/v3/issues/#create-an-issue
  await request("POST /repos/:owner/:repo/issues", {
    headers: {
      authorization: `token ${installationAccessToken}`,
    },
    mediaType: {
      previews: ["machine-man"]
    },
    owner: "hiimbex",
    repo: "testing-things",
    title: "My installation’s first issue"
  });
})

To achive the same with @octokit/auth-app, do the following

const { createAppAuth } = require("@octokit/auth-app");
const { request } = require("@octokit/request");

const auth = createAppAuth({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  installationId: process.env.INSTALLATION_ID
})

auth({ type: "installation" }).then(authentication => {
  const installationAccessToken = authentication.token

  // https://developer.github.com/v3/issues/#create-an-issue
  await request("POST /repos/:owner/:repo/issues", {
    headers: {
      authorization: `token ${installationAccessToken}`
    },
    mediaType: {
      previews: ["machine-man"]
    }
    owner: "hiimbex",
    repo: "testing-things",
    title: "My installation’s first issue"
  });
})

Or utilizing the request hook API

const { createAppAuth } = require("@octokit/auth-app");
const { request } = require("@octokit/request");

const auth = createAppAuth({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  installationId: process.env.INSTALLATION_ID,
});

const requestWithAuth = request.defaults({
  request: {
    hook: auth.hook,
  },
  mediaType: {
    previews: ["machine-man"],
  },
});

// https://developer.github.com/v3/issues/#create-an-issue
await requestWithAuth("POST /repos/:owner/:repo/issues", {
  owner: "hiimbex",
  repo: "testing-things",
  title: "My installation’s first issue",
});

Caching installation tokens

Installation tokens expire after an hour. By default, each App instance is caching up to 15000 tokens simultaneously using lru-cache. You can pass your own cache implementation by passing options.cache.{get,set} to the constructor.

Here is how the code looks like with the deprecated @octokit/app package.

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

const CACHE = {};

const app = new App({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  cache: {
    get(key) {
      return CACHE[key];
    },
    set(key, value) {
      CACHE[key] = value;
    },
  },
});

options.cache is the same for @octokit/auth-app's createAppAuth(options)

const { createAppAuth } = require("@octokit/auth-app");

const CACHE = {};

const auth = createAppAuth({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  cache: {
    get(key) {
      return CACHE[key];
    },
    set(key, value) {
      CACHE[key] = value;
    },
  },
});

Using with GitHub Enterprise

The baseUrl option can be used to override default GitHub's https://api.github.com:

const app = new App({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  baseUrl: "https://github-enterprise.com/api/v3",
});

The same option exist for @octokit/auth-app's createAppAuth(options)

const auth = createAppAuth({
  id: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  cache: {
    get(key) {
      return CACHE[key];
    },
    set(key, value) {
      CACHE[key] = value;
    },
  },
});

License

MIT