app.js

> GitHub App toolset for Node.js


- Usage
- App.defaults(options)
- Constructor
- API
- app.octokit
- app.log
- app.getInstallationOctokit
- app.eachInstallation
- app.eachRepository
- app.getInstallationUrl
- app.webhooks
- app.oauth
- Middlewares
- createNodeMiddleware(app, options)
- Contributing
- License

Usage

> [!IMPORTANT]
> As we use conditional exports, you will need to adapt your tsconfig.json by setting "moduleResolution": "node16", "module": "node16".
>
> See the TypeScript docs on package.json "exports".

> See this helpful guide on transitioning to ESM from @sindresorhus

`js
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);
// can now receive requests at /api/github/*
`

App.defaults(options)

Create a new App with custom defaults for the constructor options

`js
const MyApp = App.defaults({
Octokit: MyOctokit,
});
const app = new MyApp({ clientId, clientSecret });
// app.octokit is now an instance of MyOctokit
`

Constructor

API

$3

Octokit instance. Uses the Octokit constructor option if passed.

$3

See https://github.com/octokit/core.js#logging. Customize using the log constructor option.

$3

`js
const octokit = await app.getInstallationOctokit(123);
`

$3

`js
for await (const { octokit, installation } of app.eachInstallation.iterator()) { / ... / }
await app.eachInstallation(({ octokit, installation }) => / ... /)
`

$3

`js
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

`js
for await (const { octokit, repository } of app.eachRepository.iterator({ installationId })) { / ... / }
await app.eachRepository({ installationId }, ({ octokit, repository }) => / ... /)
`

$3

`js
const installationUrl = await app.getInstallationUrl();
return res.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 a state string that will be included in the query of the post-install redirect.

`js
const installationUrl = await app.getInstallationUrl({ state, target_id });
return res.redirect(installationUrl);
`

$3

An @octokit/webhooks instance

$3

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

$3

Middleware for Node's built in http server or express.

`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(async (req, res) => {
// middleware returns false when req is unhandled (beyond /api/github)
if (await middleware(req, res)) return;
res.writeHead(404);
res.end();
})
.listen(3000);
// can now receive user authorization callbacks at /api/github/*
`

The middleware returned from createNodeMiddleware can also serve as an
Express.js middleware directly.

Contributing

See CONTRIBUTING.md

License

MIT