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 toolset for Node.js
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 { 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);
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 });
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)
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(middleware).listen(3000);
name
|
type
|
description
|
---|
app
|
App instance
|
Required.
|
---|
options.pathPrefix
|
string
|
All exposed paths will be prefixed with the provided prefix. Defaults to "/api/github"
|
---|
log
object
|
Used for internal logging. Defaults to console with debug and info doing nothing.
|
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