Package Exports

octokit-auth-probot
octokit-auth-probot/dist-node/index.js
octokit-auth-probot/dist-src/index.js
octokit-auth-probot/dist-web/index.js

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-auth-probot) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

octokit-auth-probot

Octokit authentication strategy that supports token, app (JWT), and event-based installation authentication

octokit-auth-probot combines the authentication strategies:

It adds a new authentication type: "event-octokit", which allows to retrieve an Octokit instance which is correctly authenticated based on the Octokit constructors authentication (app or token) as well as the event, which either results in an installation access token authentication or, in case the event implies that the installation's access has been revoked, in an unauthenticated Octokit instance.

octokit-auth-probot is not meant to be used by itself, but in conjuction with @octokit/core or a compatible library.

Usage

Browsers

Browsers	Load `octokit-auth-probot` directly from esm.sh <script type="module"> import { Octokit } from "https://esm.sh/@octokit/core"; import { createProbotAuth } from "https://esm.sh/octokit-auth-probot"; </script>
Node	Install with `npm install octokit-auth-probot` const { Octokit } = require("@octokit/core"); const { createProbotAuth } = require("octokit-auth-probot"); // or: // import { Octokit } from "@octokit/core"; // import { createProbotAuth } from "octokit-auth-probot";
⚠️ For usage in browsers: The private keys provided by GitHub are in `PKCS#1` format, but the WebCrypto API only supports `PKCS#8`. You need to convert it first: openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private-key-pkcs8.key No conversion is needed in Node, both `PKCS#1` and `PKCS#8` format will work.

Load octokit-auth-probot directly from esm.sh

<script type="module">
  import { Octokit } from "https://esm.sh/@octokit/core";
  import { createProbotAuth } from "https://esm.sh/octokit-auth-probot";
</script>

Node

Install with npm install octokit-auth-probot

const { Octokit } = require("@octokit/core");
const { createProbotAuth } = require("octokit-auth-probot");
// or:
// import { Octokit } from "@octokit/core";
// import { createProbotAuth } from "octokit-auth-probot";

⚠️ For usage in browsers: The private keys provided by GitHub are in PKCS#1 format, but the WebCrypto API only supports PKCS#8. You need to convert it first:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private-key-pkcs8.key

No conversion is needed in Node, both PKCS#1 and PKCS#8 format will work.

const { Octokit } = require("@octokit/core");
const { createProbotAuth } = require("octokit-auth-probot");

const ProbotOctokit = Octokit.defaults({
  authStrategy: createProbotAuth,
});

Token authentication

const octokit = new ProbotOctokit({
  auth: {
    token: "secret 123",
  },
});

Note: when using octokit.auth({ type: "installation", factory }), factory(options) will be called with options.octokit, options.octokitOptions, plus any other properties that have been passed to octokit.auth() besides type and factory. In all other cases, octokit.auth() will resolve with an oauth authentication object, no matter the passed options.

App authentication

const octokit = new ProbotOctokit({
  auth: {
    appId: 123,
    privateKey: `----BEGIN RSA PRIVATE KEY----- ...`,
  },
});

Unauthenticated

const octokit = new ProbotOctokit();

This is useful if you need to send a request without access to authentication. Probot's use case here is Create a GitHub App from a manifest (POST /app-manifests/{code}/conversions), which is used to register a GitHub app and retrieve the credentials in return.

Get authenticated octokit instance based on event

const eventOctokit = await octokit.auth({
  type: "event-octokit",
  event: { name: "push", payload: { installation: { id: 123 } } }, // event payload
});

eventOctokit is now authenticated in one of three ways:

If octokit was authenticated using a token, eventOctokit is authenticated with the same token. In fact, eventOctokit is octokit
If event name is installation and payload.action is either suspend or deleted, then eventOctokit is unauthenticated using @octokit/auth-unauthenticated
Otherwise eventOctokit is authenticated as installation based on payload.installation.id

LICENSE

ISC