Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 609 Commits
.github		.github
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Repository files navigation

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

Important

As we useconditional exports, you will need to adapt yourtsconfig.json by setting"moduleResolution": "node16", "module": "node16".

See the TypeScript docs onpackage.json "exports".
See thishelpful guide on transitioning to ESM from@sindresorhus

constapp=newApp({appId:123,privateKey:"-----BEGIN PRIVATE KEY-----\n...",oauth:{clientId:"0123",clientSecret:"0123secret",},webhooks:{secret:"secret",},});const{ data}=awaitapp.octokit.request("/app");console.log("authenticated as %s",data.name);forawait(const{ installation}ofapp.eachInstallation.iterator()){forawait(const{ octokit, repository}ofapp.eachRepository.iterator({installationId:installation.id,})){awaitoctokit.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})=>{awaitoctokit.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}=awaitoctokit.request("GET /user");console.log(`Token retrieved for${data.login}`);});require("http").createServer(createNodeMiddleware(app)).listen(3000);// can now receive requests at /api/github/*

`App.defaults(options)`

Create a newApp with custom defaults for theconstructor options

constMyApp=App.defaults({Octokit:MyOctokit,});constapp=newMyApp({ clientId, clientSecret});// app.octokit is now an instance of MyOctokit

Constructor

name	type	description
`appId`	`number`	Required. Find theApp 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");newApp({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 OAuthClient ID on the app’s about page in settings.
`oauth.clientSecret`	`number`	Find the OAuthClient 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 theOctokit constructor option if passed.

`app.log`

Seehttps://github.com/octokit/core.js#logging. Customize using thelog constructor option.

`app.getInstallationOctokit`

constoctokit=awaitapp.getInstallationOctokit(123);

`app.eachInstallation`

forawait(const{ octokit, installation}ofapp.eachInstallation.iterator()){/* ... */}awaitapp.eachInstallation(({ octokit, installation})=>/* ... */)

`app.eachRepository`

forawait(const{ octokit, repository}ofapp.eachRepository.iterator()){/* ... */}awaitapp.eachRepository(({ octokit, repository})=>/* ... */)

Optionally pass installation ID to iterate through all repositories in one installation

forawait(const{ octokit, repository}ofapp.eachRepository.iterator({ installationId})){/* ... */}awaitapp.eachRepository({ installationId},({ octokit, repository})=>/* ... */)

`app.getInstallationUrl`

constinstallationUrl=awaitapp.getInstallationUrl();returnres.redirect(installationUrl);

Optionally pass the ID of a GitHub organization or user to request installation on that specific target.

If the user will be sent to a redirect URL after installation (such as if you request user authorization during installation), you can also supply astate string that will be included in the query of the post-install redirect.

constinstallationUrl=awaitapp.getInstallationUrl({ state, target_id});returnres.redirect(installationUrl);

`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 orexpress.

const{ App, createNodeMiddleware}=require("@octokit/app");constapp=newApp({appId:123,privateKey:"-----BEGIN PRIVATE KEY-----\n...",oauth:{clientId:"0123",clientSecret:"0123secret",},webhooks:{secret:"secret",},});constmiddleware=createNodeMiddleware(app);require("http").createServer(async(req,res)=>{// `middleware` returns `false` when `req` is unhandled (beyond `/api/github`)if(awaitmiddleware(req,res))return;res.writeHead(404);res.end();}).listen(3000);// can now receive user authorization callbacks at /api/github/*

The middleware returned fromcreateNodeMiddleware can also serve as anExpress.js middleware directly.

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. `</td></tr>`