Customized Octokit for Octoherd

Usage no npm install needed!

<script type="module">
  import octoherdOctokit from 'https://cdn.skypack.dev/@octoherd/octokit';



Customized Octokit for Octoherd



Load @octoherd/octokit directly from cdn.skypack.dev

<script type="module">
  import { Octokit } from "https://cdn.skypack.dev/@octoherd/octokit";
Node (12+)

Install with npm install @octoherd/octokit

import { Octokit } from "@octoherd/octokit";

Load @octoherd/octokit directly from cdn.skypack.dev with the ?dts query

import { Octokit } from "https://cdn.skypack.dev/@octoherd/octokit?dts";
import { Octokit } from "@octoherd/octokit";

const octokit = new Octokit({
  auth: /* token here, create one at https://github.com/settings/tokens/new */,

const { data: me } = await octokit.request("GET /user")

By default you authenticate using a token, but you can use any authentication strategy.

REST API requests and GraphQL queries

@ocotkit/octokit is built on @octokit/core. You can send requests to GitHub's REST API using octokit.request and GraphQL queries octokit.graphql.


By default, messages are logged with meta data using console.info, console.warn, and console.error. octokit.log.debug is a no-op, unless options.octoherd.debug is set to true.

Important: options.log is ignored. Setting it has no effect.

You can log simple messages, interpolation is supported.

octokit.log.info("Checking repository %s", repository.full_name);

You can pass extra meta information as the first argument

  { id: repository.id },
  "Checking repository %s",

You can also just log meta information for reporting later

  id: repository.id,
  owner: repositor.owner.login,
  repo: repository.name,
  private: repository.private,

The way data is logged can be customized using options.octoherd.onLogMessage and options.octoherd.onLogData.

const octokit = new Octokit({
  octoherd: {
    onLogData(data) {
      // e.g. write data as JSON line to debug log file
      // data always has `.level`, and `.time` properties. `.msg` is set from the log message if set.
    onLogMessage(level, message, additionalData) {
      // level is one of: debug, info, warn, error.
      // message is the log message
      // additionalData is any data that was passed as first argument to the log methods. It defaults to {}
          ? `${message} ${chalk.gray(JSON.stringify(additionalData))}`
          : message

Additional context can be changed at runtime using octokit.log.setContext(context). The additional context is only passed to options.octoherd.onLogData

octokit.log.setContext({ repo_id: 123 });
// data passed to `onLogData` will be { repo_id: 123, msg: "test", level: "info", time: 0 }
// additionalData passed to `onLogMessage` will not have the `.repo_id` property

Built-in plugins

@octoherd/octokit comes with a few plugins out of the box:

You can use octokit.paginate() or octokit.paginate.iterator() for paginating REST API requests.

The retry & throttling plugins hook into the request lifecycle, retries requests in case of unrelated server errors, and throttles requests to avoid hitting rate or abuse limits.


You can extend @octoherd/octokit with hooks and plugins