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.
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.
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.
const App = require('@octokit/app')
const request = require('@octokit/request')
const APP_ID = 1
const PRIVATE_KEY = '-----BEGIN RSA PRIVATE KEY-----\n...'
const app = new App({ id: APP_ID, privateKey: PRIVATE_KEY })
const jwt = app.getSignedJsonWebToken()
const { data } = await request('GET /repos/:owner/:repo/installation', {
owner: 'hiimbex',
repo: 'testing-things',
headers: {
authorization: `Bearer ${jwt}`,
accept: 'application/vnd.github.machine-man-preview+json'
}
})
const installationId = data.id
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.
const App = require('@octokit/app')
const request = require('@octokit/request')
const APP_ID = 1
const PRIVATE_KEY = '-----BEGIN RSA PRIVATE KEY-----\n...'
const app = new App({ id: APP_ID, privateKey: PRIVATE_KEY })
const installationAccessToken = await app.getInstallationAccessToken({ installationId })
await request('POST /repos/:owner/:repo/issues', {
owner: 'hiimbex',
repo: 'testing-things',
headers: {
authorization: `token ${installationAccessToken}`,
accept: 'application/vnd.github.machine-man-preview+json'
},
title: 'My installation’s first issue'
})
Caching installation tokens
Installation tokens expire after an hour. By default, @octokit/app
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.
const App = require('@octokit/app')
const APP_ID = 1
const PRIVATE_KEY = '-----BEGIN RSA PRIVATE KEY-----\n...'
const CACHE = {}
const app = new App({
id: APP_ID,
privateKey: 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: APP_ID,
privateKey: PRIVATE_KEY,
baseUrl: 'https://github-enterprise.com/api/v3'
})
License
MIT