octokit/rest.js

Import the Octokit constructor based on your platform.

Browsers

<script type="module">
  import { Octokit } from "https://cdn.pika.dev/@octokit/rest";
</script>

Node

const { Octokit } = require("@octokit/rest");
// or: import { Octokit } from "@octokit/rest";

const { Octokit } = require("@octokit/rest");

Now instantiate your octokit API. All options are optional, but authentication is strongly encouraged.

const octokit = new Octokit({

You can set auth to a personal access token string.

Learn more about authentication.

  auth: "secret123",

Setting a user agent is required. It defaults to octokit/rest.js v1.2.3 where v1.2.3 is the current version of @octokit/rest, but you should set it to something that identifies your app or script.

  userAgent: 'myApp v1.2.3',

API Previews can be enabled globally by setting the previews option. They can be set per-request as well.

Learn more about API Previews.

  previews: ['jean-grey', 'symmetra'],

A default time zone can be enabled by setting the timeZone option.

  timeZone: 'Europe/Amsterdam',

Learn more about using time zones with the GitHub API.

In order to use Octokit with GitHub Enterprise, set the baseUrl option.

  baseUrl: 'https://api.github.com',

For custom logging, pass an object with debug, info, warn and error methods as the log option.

Learn more about logging and debugging.

  log: {
    debug: () => {},
    info: () => {},
    warn: console.warn,
    error: console.error
  },

Custom request options can be passed as request.* options. See @octokit/request options. The same options can be passed to each endpoint request method.

  request: {
    agent: undefined,
    fetch: undefined,
    timeout: 0
  }
})

Most of GitHub’s REST API endpoints have matching methods. All endpoint methods are asynchronous, in order to use await in the code examples, we wrap them into an anonymous async function.

(async () => {

For example to retrieve a pull request, use octokit.pulls.get(). We recommend to use the search above to find the endpoint method you are looking for

const { data: pullRequest } = await octokit.pulls.get({
  owner: "octokit",
  repo: "rest.js",
  pull_number: 123,
});

Some API endpoints support alternative response formats, see Media types. For example, to request the above pull request in a diff format, pass the mediaType.format option.

Learn more about request formats.

const { data: diff } = await octokit.pulls.get({
  owner: "octokit",
  repo: "rest.js",
  pull_number: 123,
  mediaType: {
    format: "diff",
  },
});

For the API endpoints that do not have a matching method, such as the root endpoint or legacy endpoints, you can send custom requests.

Learn more about custom requests.

const { data: root } = await octokit.request("GET /");

You can also register custom endpoint methods, which is particularly useful if you participate in a private beta.

Learn more about custom endpoint methods.

await octokit.registerEndpoints({
  misc: {
    getRoot: {
      method: "GET",
      url: "/",
    },
  },
});

Some endpoints return a list which has to be paginated in order to retrieve the complete data set.

Learn more about pagination.

  octokit.paginate(octokit.issues.listForRepo, {
    owner: 'octokit',
    repo: 'rest.js'
  })
    .then(issues => {
      // issues is an array of all issue objects
    })
})

You can add more functionality with plugins. We recommend the retry and throttling plugins.

Learn more about throttling, automatic retries and building your own Plugins.

import { retry } from "@octokit/plugin-retry";
import { throttling } from "@octokit/plugin-throttling";

const MyOctokit = Octokit.plugin(retry, throttling);

Octokit.plugin() returns a new constructor. The same options can be passed to the constructor. The options are passed on to all plugin functions as the 2nd argument.

const myOctokit = new MyOctokit({
  auth: "secret123",
  throttle: {
    onRateLimit: (retryAfter, options) => {
      myOctokit.log.warn(
        `Request quota exhausted for request ${options.method} ${options.url}`
      );

      if (options.request.retryCount === 0) {
        // only retries once
        myOctokit.log.info(`Retrying after ${retryAfter} seconds!`);
        return true;
      }
    },
    onAbuseLimit: (retryAfter, options) => {
      // does not retry, only logs a warning
      myOctokit.log.warn(
        `Abuse detected for request ${options.method} ${options.url}`
      );
    },
  },
  retry: {
    doNotRetry: ["429"],
  },
});

Authentication is optional for some REST API endpoints accessing public data, but is required for GraphQL queries. Using authentication also increases your API rate limit.

By default, Octokit authenticates using the token authentication strategy. Pass in a token using options.auth. It can be a personal access token, an OAuth token, an installation access token or a JSON Web Token for GitHub App authentication. The Authorization header will be set according to the type of token.

const { Octokit } = require("@octokit/rest");

const octokit = new Octokit({
  auth: "mypersonalaccesstoken123",
});

const { data } = await octokit.request("/user");

To use a different authentication strategy, set options.authStrategy. The officially supported authentication strategies are listed on the @octokit/auth README.

Here is an example for GitHub App authentication

const { Octokit } = require("@octokit/rest");
const { createAppAuth } = require("@octokit/auth-app");

const appOctokit = new Octokit({
  authStrategy: createAppAuth,
  auth: {
    id: 123,
    privateKey: process.env.PRIVATE_KEY,
  },
});

const { data } = await appOctokit.request("/app");

The .auth() method returned by the current authentication strategy can be accessed at octokit.auth(). Example

const { token } = await appOctokit.auth({
  type: "installation",
  installationId: 123,
});

To enable any of GitHub’s API Previews, pass the previews option to the GitHub constructor

const octokit = new Octokit({
  previews: ["mercy-preview"],
});

Previews can also be enabled for a single request by passing the mediaType.preview option

const {
  data: { topics },
} = await octokit.repos.get({
  owner: "octokit",
  repo: "rest.js",
  mediaType: {
    previews: ["symmetra"],
  },
});

Some API endpoints support alternative response formats, see Media types.

For example, to request a pull request as diff format, set the mediaType.format option

const { data: prDiff } = await octokit.pulls.get({
  owner: "octokit",
  repo: "rest.js",
  pull_number: 1278,
  mediaType: {
    format: "diff",
  },
});

The AbortController interface can be used to abort one or more requests as and when desired. When the request is initiated, an AbortSignal instance can be passed as an option inside the request's options object. For usage in Node, the abort-controller package can be used.

const controller = new AbortController();
const { data: prDiff } = await octokit.pulls.get({
  owner: "octokit",
  repo: "rest.js",
  pull_number: 1278,
  request: {
    signal: controller.signal,
  },
});

Use controller.abort() to abort the request when desired.

To send custom requests you can use the lower-level octokit.request() method

octokit.request("GET /");

The baseUrl, headers and other defaults are already set. For more information on the octokit.request() API see octokit/request.js

All the endpoint methods such as octokit.repos.get() are aliases of octokit.request() with pre-bound default options. So you can use the @octokit/request API to get the default options or get generic request option to use with your preferred request library.

const defaultOptions = octokit.repos.get.endpoint.DEFAULTS;
const requestOptions = octokit.repos.get.endpoint({
  owner: "octokit",
  repo: "rest.js",
});

Note that authentication is not applied when retrieving request options from the *.endpoint APIs.

All endpoint methods starting with .list* do not return all results at once but instead return the first 30 items by default, see also GitHub’s REST API pagination documentation.

To automatically receive all results across all pages, you can use the octokit.paginate() method:

octokit
  .paginate("GET /repos/:owner/:repo/issues", {
    owner: "octokit",
    repo: "rest.js",
  })
  .then((issues) => {
    // issues is an array of all issue objects. It is not wrapped in a { data, headers, status, url } object
    // like results from `octokit.request()` or any of the endpoint methods such as `octokit.issues.listForRepo()`
  });

octokit.paginate() accepts the same options as octokit.request(). You can optionally pass an additional function to map the results from each response. The map must return a new value, usually an array with mapped data.

Note: the map function is called with the { data, headers, status, url } response object. The data property is guaranteed to be an array of the result items, even for list endpoints that respond with an object instead of an array, such as the search endpoints.

octokit
  .paginate(
    "GET /repos/:owner/:repo/issues",
    { owner: "octokit", repo: "rest.js" },
    (response) => response.data.map((issue) => issue.title)
  )
  .then((issueTitles) => {
    // issueTitles is now an array with the titles only
  });

To stop paginating early, you can call the done() function passed as 2nd argument to the response map function. Note that you still have to return the value you want to map the response to, otherwise the last response will be mapped to undefined.

octokit.paginate("GET /organizations", (response, done) => {
  if (response.data.find((issues) => issue.body.includes("something"))) {
    done();
  }
  return response.data;
});

To paginate responses for one of the registered endpoint methods such as octokit.issues.listForRepo() you can pass the method directly as first argument to octokit.paginate:

octokit
  .paginate(octokit.issues.listForRepo, {
    owner: "octokit",
    repo: "rest.js",
  })
  .then((issues) => {
    // issues is an array of all issue objects
  });

If your runtime environment supports async iterators (such as most modern browsers and Node 10+), you can iterate through each response

for await (const response of octokit.paginate.iterator(
  octokit.issues.listForRepo,
  {
    owner: "octokit",
    repo: "rest.js",
  }
)) {
  // do whatever you want with each response, break out of the loop, etc.
}

octokit.paginate.iterator() accepts the same options as octokit.paginate().

You can customize Octokit’s request lifecycle with hooks. Available methods are

octokit.hook.before("request", async (options) => {
  validate(options);
});
octokit.hook.after("request", async (response, options) => {
  console.log(`${options.method} ${options.url}: ${response.status}`);
});
octokit.hook.error("request", async (error, options) => {
  if (error.status === 304) {
    return findInCache(error.headers.etag);
  }

  throw error;
});
octokit.hook.wrap("request", async (request, options) => {
  // add logic before, after, catch errors or replace the request altogether
  return request(options);
});

See before-after-hook for more details on the 4 methods.

Note: octokit.registerEndpoints() has been deprecated.

Instead of

await octokit.registerEndpoints({
  misc: {
    getRoot: {
      method: "GET",
      url: "/",
    },
  },
});

do

Object.assign(octokit.misc, {
  getRoot: octokit.request.defaults({
    method: "GET",
    url: "/",
  }),
});

If you use octokit.registerEndpoints() in a plugin, return an object instead:

function myPlugin(octokit, options) {
  return {
    misc: {
      octokit.request.defaults({ method: "GET", url: "/" })
    }
  }
}

You can register custom endpoint methods such as octokit.repos.get() using the octokit.registerEndpoints(routes) method

octokit.registerEndpoints({
  foo: {
    bar: {
      method: "PATCH",
      url: "/repos/:owner/:repo/foo",
      headers: {
        accept: "application/vnd.github.foo-bar-preview+json",
      },
      params: {
        owner: {
          required: true,
          type: "string",
        },
        repo: {
          required: true,
          type: "string",
        },
        baz: {
          required: true,
          type: "string",
          enum: ["qux", "quux", "quuz"],
        },
      },
    },
  },
});

octokit.foo.bar({
  owner: "octokit",
  repo: "rest.js",
  baz: "quz",
});

This is useful when you participate in private beta features and prefer the convenience of methods for the new endpoints instead of using octokit.request().

You can customize and extend Octokit’s functionality using plugins

// index.js
const Octokit = require("@octokit/rest");
const MyOctokit = Octokit.plugin(
  require("./lib/my-plugin"),
  require("octokit-plugin-example")
);

// lib/my-plugin.js
module.exports = (octokit, options = { greeting: "Hello" }) => {
  // hook into the request lifecycle
  octokit.hook.wrap("request", async (request, options) => {
    const time = Date.now();
    const response = await request(options);
    octokit.log.info(
      `${options.method} ${options.url} – ${response.status} in ${
        Date.now() - time
      }ms`
    );
    return response;
  });

  // add a custom method: octokit.helloWorld()
  return {
    helloWorld: () => console.log(`${options.greeting}, world!`),
  };
};

.plugin accepts a function or an array of functions.

We recommend using Octokit’s log methods to help users of your plugin with debugging.

You can add new methods to the octokit instance passed as the first argument to the plugin function. The 2nd argument is the options object passed to the constructor when instantiating the octokit client.

const octokit = new MyOctokit({ greeting: "Hola" });
octokit.helloWorld();
// Hola, world!

When you send too many requests in too little time you will likely hit errors due to rate and/or abuse limits.

In order to automatically throttle requests as recommended in GitHub’s best practices for integrators, we recommend you install the @octokit/plugin-throttling plugin.

The throttle.onAbuseLimit and throttle.onRateLimit options are required. Return true to automatically retry the request after retryAfter seconds.

const { Octokit } = require("@octokit/rest");
const { throttling } = require("@octokit/plugin-throttling");
const MyOctokit = Octokit.plugin(throttling);

const octokit = new MyOctokit({
  auth: "token " + process.env.TOKEN,
  throttle: {
    onRateLimit: (retryAfter, options) => {
      octokit.log.warn(
        `Request quota exhausted for request ${options.method} ${options.url}`
      );

      if (options.request.retryCount === 0) {
        // only retries once
        console.log(`Retrying after ${retryAfter} seconds!`);
        return true;
      }
    },
    onAbuseLimit: (retryAfter, options) => {
      // does not retry, only logs a warning
      octokit.log.warn(
        `Abuse detected for request ${options.method} ${options.url}`
      );
    },
  },
});

Many common request errors can be easily remediated by retrying the request. We recommend installing the @octokit/plugin-retry plugin for Automatic retries in these cases

const { Octokit } = require("@octokit/rest");
const { retry } = require("@octokit/plugin-retry");
const MyOctokit = Octokit.plugin(retry);

const octokit = new MyOctokit();

// all requests sent with the `octokit` instance are now retried up to 3 times for recoverable errors.

Octokit has 4 built-in log methods

1. octokit.log.debug(message[, additionalInfo])
2. octokit.log.info(message[, additionalInfo])
3. octokit.log.warn(message[, additionalInfo])
4. octokit.log.error(message[, additionalInfo])

They can be configured using the log client option. By default, octokit.log.debug() and octokit.log.info() are no-ops, while the other two call console.warn() and console.error() respectively.

This is useful if you build reusable plugins.

The simplest way to receive debug information is to set the log client option to console.

const octokit = require("@octokit/rest")({
  log: console,
});

octokit.request("/");

This will log

request { method: 'GET',
  baseUrl: 'https://api.github.com',
  headers:
   { accept: 'application/vnd.github.v3+json',
     'user-agent':
      'octokit.js/0.0.0-development Node.js/10.15.0 (macOS Mojave; x64)' },
  request: {},
  url: '/' }
GET / - 200 in 514ms

If you like to support a configurable log level, we recommend using the console-log-level module

const octokit = require("@octokit/rest")({
  log: require("console-log-level")({ level: "info" }),
});

octokit.request("/");

This will only log

GET / - 200 in 514ms

Actions

Cancel a workflow run

Cancels a workflow run using its id. Anyone with write access to the repository and an access token with the repo scope can use this endpoint. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.cancelWorkflowRun({
  owner,
  repo,
  run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Create or update a secret for a repository

Creates or updates a secret with an encrypted value. Encrypt your secret using LibSodium. Anyone with write access to the repository and an access token with the repo scope can use this endpoint. GitHub Apps must have the secrets permission to use this endpoint.

Encrypt your secret using the tweetsodium library.

Encrypt your secret using pynacl with Python 3.

Encrypt your secret using the Sodium.Core package.

Encrypt your secret using the rbnacl gem.

octokit.actions.createOrUpdateSecretForRepo({
  owner,
  repo,
  name,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a registration token for a repository

Deprecated: This method has been renamed to actions.createRegistrationTokenForRepo

Returns a token that you can pass to the config script. The token expires after one hour. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

Configure your self-hosted runner, replacing TOKEN with the registration token provided by this endpoint.

octokit.actions.createRegistrationToken({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a registration token for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

Returns a token that you can pass to the config script. The token expires after one hour. Anyone with admin access to the organization can use this endpoint.

Configure your self-hosted runner, replacing TOKEN with the registration token provided by this endpoint.

octokit.actions.createRegistrationTokenForOrg({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a registration token for a repository

Returns a token that you can pass to the config script. The token expires after one hour. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

Configure your self-hosted runner, replacing TOKEN with the registration token provided by this endpoint.

octokit.actions.createRegistrationTokenForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a remove token for a repository

Deprecated: This method has been renamed to actions.createRemoveTokenForRepo

Returns a token that you can pass to remove a self-hosted runner from a repository. The token expires after one hour. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

Remove your self-hosted runner from a repository, replacing TOKEN with the remove token provided by this endpoint.

octokit.actions.createRemoveToken({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a remove token for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

Returns a token that you can pass to the config script to remove a self-hosted runner from an organization. The token expires after one hour. Anyone with admin access to the organization can use this endpoint.

To remove your self-hosted runner from an organization, replace TOKEN with the remove token provided by this endpoint.

octokit.actions.createRemoveTokenForOrg({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a remove token for a repository

Returns a token that you can pass to remove a self-hosted runner from a repository. The token expires after one hour. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

Remove your self-hosted runner from a repository, replacing TOKEN with the remove token provided by this endpoint.

octokit.actions.createRemoveTokenForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete an artifact

Deletes an artifact for a workflow run. Anyone with write access to the repository and an access token with the repo scope can use this endpoint. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.deleteArtifact({
  owner,
  repo,
  artifact_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete a secret from a repository

Deletes a secret in a repository using the secret name. Anyone with write access to the repository and an access token with the repo scope can use this endpoint. GitHub Apps must have the secrets permission to use this endpoint.

octokit.actions.deleteSecretFromRepo({
  owner,
  repo,
  name,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete a self-hosted runner from an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

Forces the removal of a self-hosted runner from an organization. You can use this endpoint to completely remove the runner when the machine you were using no longer exists. Anyone with admin access to the organization can use this endpoint.

octokit.actions.deleteSelfHostedRunnerFromOrg({
  org,
  runner_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete a self-hosted runner from a repository

Forces the removal of a self-hosted runner from a repository. You can use this endpoint to completely remove the runner when the machine you were using no longer exists. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

octokit.actions.deleteSelfHostedRunnerFromRepo({
  owner,
  repo,
  runner_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete workflow run logs

Deletes all logs for a workflow run. Anyone with write access to the repository and an access token with the repo scope can use this endpoint. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.deleteWorkflowRunLogs({
  owner,
  repo,
  run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Download an artifact

Gets a redirect URL to download an archive for a repository. This URL expires after 1 minute. Look for Location: in the response header to find the URL for the download. The :archive_format must be zip. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

Call this endpoint using the -v flag, which enables verbose output and allows you to see the download URL in the header. To download the file into the current working directory, specify the filename using the -o flag.

octokit.actions.downloadArtifact({
  owner,
  repo,
  artifact_id,
  archive_format,
});

Parameters

See also: GitHub Developer Guide documentation.

Download workflow job logs

Gets a redirect URL to download a plain text file of logs for a workflow job. This link expires after 1 minute. Look for Location: in the response header to find the URL for the download. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

Call this endpoint using the -v flag, which enables verbose output and allows you to see the download URL in the header. To download the file into the current working directory, specify the filename using the -o flag.

octokit.actions.downloadWorkflowJobLogs({
  owner,
  repo,
  job_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Download workflow run logs

Gets a redirect URL to download an archive of log files for a workflow run. This link expires after 1 minute. Look for Location: in the response header to find the URL for the download. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

Call this endpoint using the -v flag, which enables verbose output and allows you to see the download URL in the header. To download the file into the current working directory, specify the filename using the -o flag.

octokit.actions.downloadWorkflowRunLogs({
  owner,
  repo,
  run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get an artifact

Gets a specific artifact for a workflow run. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.getArtifact({
  owner,
  repo,
  artifact_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get your public key

Gets your public key, which you must store. You need your public key to use other secrets endpoints. Use the returned key to encrypt your secrets. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the secrets permission to use this endpoint.

octokit.actions.getPublicKey({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a secret

Gets a single secret without revealing its encrypted value. Anyone with write access to the repository and an access token with the repo scope can use this endpoint. GitHub Apps must have the secrets permission to use this endpoint.

octokit.actions.getSecret({
  owner,
  repo,
  name,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a self-hosted runner for a repository

Deprecated: This method has been renamed to actions.getSelfHostedRunnerForRepo

Gets a specific self-hosted runner. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

octokit.actions.getSelfHostedRunner({
  owner,
  repo,
  runner_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a self-hosted runner for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

Gets a specific self-hosted runner for an organization. Anyone with admin access to the organization can use this endpoint.

octokit.actions.getSelfHostedRunnerForOrg({
  org,
  runner_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a self-hosted runner for a repository

Gets a specific self-hosted runner. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

octokit.actions.getSelfHostedRunnerForRepo({
  owner,
  repo,
  runner_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a workflow

Gets a specific workflow. You can also replace :workflow_id with :workflow_file_name. For example, you could use main.yml. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.getWorkflow({
  owner,
  repo,
  workflow_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a workflow job

Gets a specific job in a workflow run. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.getWorkflowJob({
  owner,
  repo,
  job_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a workflow run

Gets a specific workflow run. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.getWorkflowRun({
  owner,
  repo,
  run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List artifacts for a repository

Lists all artifacts for a repository. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.listArtifactsForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List runner applications for a repository

Deprecated: This method has been renamed to actions.listRunnerApplicationsForRepo

Lists binaries for the runner application that you can download and run. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

octokit.actions.listDownloadsForSelfHostedRunnerApplication({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List jobs for a workflow run

Lists jobs for a workflow run. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint. You can use parameters to narrow the list of results. For more information about using parameters, see Parameters.

octokit.actions.listJobsForWorkflowRun({
  owner,
  repo,
  run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List repository workflow runs

Lists all workflow runs for a repository. You can use parameters to narrow the list of results. For more information about using parameters, see Parameters.

Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.listRepoWorkflowRuns({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List repository workflows

Lists the workflows in a repository. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.listRepoWorkflows({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List runner applications for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

Lists binaries for the runner application that you can download and run. Anyone with admin access to the organization can use this endpoint.

octokit.actions.listRunnerApplicationsForOrg({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List runner applications for a repository

Lists binaries for the runner application that you can download and run. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

octokit.actions.listRunnerApplicationsForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List secrets for a repository

Lists all secrets available in a repository without revealing their encrypted values. Anyone with write access to the repository and an access token with the repo scope can use this endpoint. GitHub Apps must have the secrets permission to use this endpoint.

octokit.actions.listSecretsForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List self-hosted runners for an organization

Warning: The self-hosted runners API for organizations is currently in public beta and subject to change.

Lists all self-hosted runners for an organization. Anyone with admin access to the organization can use this endpoint.

octokit.actions.listSelfHostedRunnersForOrg({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List self-hosted runners for a repository

Lists all self-hosted runners for a repository. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

octokit.actions.listSelfHostedRunnersForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Download workflow job logs

Deprecated: This method has been renamed to actions.downloadWorkflowJobLogs

Gets a redirect URL to download a plain text file of logs for a workflow job. This link expires after 1 minute. Look for Location: in the response header to find the URL for the download. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

Call this endpoint using the -v flag, which enables verbose output and allows you to see the download URL in the header. To download the file into the current working directory, specify the filename using the -o flag.

octokit.actions.listWorkflowJobLogs({
  owner,
  repo,
  job_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List workflow run artifacts

Lists artifacts for a workflow run. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.listWorkflowRunArtifacts({
  owner,
  repo,
  run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Download workflow run logs

Deprecated: This method has been renamed to actions.downloadWorkflowRunLogs

Gets a redirect URL to download an archive of log files for a workflow run. This link expires after 1 minute. Look for Location: in the response header to find the URL for the download. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope. GitHub Apps must have the actions permission to use this endpoint.

Call this endpoint using the -v flag, which enables verbose output and allows you to see the download URL in the header. To download the file into the current working directory, specify the filename using the -o flag.

octokit.actions.listWorkflowRunLogs({
  owner,
  repo,
  run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List workflow runs

List all workflow runs for a workflow. You can also replace :workflow_id with :workflow_file_name. For example, you could use main.yml. You can use parameters to narrow the list of results. For more information about using parameters, see Parameters.

Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the repo scope.

octokit.actions.listWorkflowRuns({
  owner,
  repo,
  workflow_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Re-run a workflow

Re-runs your workflow run using its id. Anyone with write access to the repository and an access token with the repo scope can use this endpoint. GitHub Apps must have the actions permission to use this endpoint.

octokit.actions.reRunWorkflow({
  owner,
  repo,
  run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete a self-hosted runner from a repository

Deprecated: This method has been renamed to actions.deleteSelfHostedRunnerFromRepo

Forces the removal of a self-hosted runner from a repository. You can use this endpoint to completely remove the runner when the machine you were using no longer exists. Anyone with admin access to the repository and an access token with the repo scope can use this endpoint.

octokit.actions.removeSelfHostedRunner({
  owner,
  repo,
  runner_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Activity

Check if a repository is starred by the authenticated user

octokit.activity.checkRepoIsStarredByAuthenticatedUser({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Check if a repository is starred by the authenticated user

Deprecated: This method has been renamed to activity.checkRepoIsStarredByAuthenticatedUser

octokit.activity.checkStarringRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete a repository subscription

This endpoint should only be used to stop watching a repository. To control whether or not you wish to receive notifications from a repository, set the repository's subscription manually.

octokit.activity.deleteRepoSubscription({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete a thread subscription

Mutes all future notifications for a conversation until you comment on the thread or get an @mention. If you are watching the repository of the thread, you will still receive notifications. To ignore future notifications for a repository you are watching, use the Set a thread subscription endpoint and set ignore to true.

octokit.activity.deleteThreadSubscription({
  thread_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get feeds

GitHub provides several timeline resources in Atom format. The Feeds API lists all the feeds available to the authenticated user:

• Timeline: The GitHub global public timeline
• User: The public timeline for any user, using URI template
• Current user public: The public timeline for the authenticated user
• Current user: The private timeline for the authenticated user
• Current user actor: The private timeline for activity created by the authenticated user
• Current user organizations: The private timeline for the organizations the authenticated user is a member of.
• Security advisories: A collection of public announcements that provide information about security-related vulnerabilities in software on GitHub.

Note: Private feeds are only returned when authenticating via Basic Auth since current feed URIs use the older, non revocable auth tokens.

octokit.activity.getFeeds();

Parameters

This endpoint has no parameters

See also: GitHub Developer Guide documentation.

Get a repository subscription

octokit.activity.getRepoSubscription({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a thread

octokit.activity.getThread({
  thread_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Mark notifications as read

Deprecated: This method has been renamed to activity.getThreadSubscriptionForAuthenticatedUser

Marks all notifications as "read" removes it from the default view on GitHub. If the number of notifications is too large to complete in one request, you will receive a 202 Accepted status and GitHub will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List notifications for the authenticated user endpoint and pass the query parameter all=false.

octokit.activity.getThreadSubscription();

Parameters

See also: GitHub Developer Guide documentation.

Get a thread subscription for the authenticated user

This checks to see if the current user is subscribed to a thread. You can also get a repository subscription.

Note that subscriptions are only generated if a user is participating in a conversation--for example, they've replied to the thread, were @mentioned, or manually subscribe to a thread.

octokit.activity.getThreadSubscriptionForAuthenticatedUser({
  thread_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List events for the authenticated user

If you are authenticated as the given user, you will see your private events. Otherwise, you'll only see public events.

octokit.activity.listEventsForAuthenticatedUser({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

List organization events for the authenticated user

Deprecated: This method has been renamed to activity.listOrgEventsForAuthenticatedUser

This is the user's organization dashboard. You must be authenticated as the user to view this.

octokit.activity.listEventsForOrg({
  username,
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List events for the authenticated user

Deprecated: This method has been renamed to activity.listEventsForAuthenticatedUser

If you are authenticated as the given user, you will see your private events. Otherwise, you'll only see public events.

octokit.activity.listEventsForUser({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

Get feeds

Deprecated: This method has been renamed to activity.getFeeds

GitHub provides several timeline resources in Atom format. The Feeds API lists all the feeds available to the authenticated user:

• Timeline: The GitHub global public timeline
• User: The public timeline for any user, using URI template
• Current user public: The public timeline for the authenticated user
• Current user: The private timeline for the authenticated user
• Current user actor: The private timeline for activity created by the authenticated user
• Current user organizations: The private timeline for the organizations the authenticated user is a member of.
• Security advisories: A collection of public announcements that provide information about security-related vulnerabilities in software on GitHub.

Note: Private feeds are only returned when authenticating via Basic Auth since current feed URIs use the older, non revocable auth tokens.

octokit.activity.listFeeds();

Parameters

This endpoint has no parameters

See also: GitHub Developer Guide documentation.

List notifications for the authenticated user

Deprecated: This method has been renamed to activity.listNotificationsForAuthenticatedUser

List all notifications for the current user, sorted by most recently updated.

The following example uses the since parameter to list notifications that have been updated after the specified time.

octokit.activity.listNotifications();

Parameters

See also: GitHub Developer Guide documentation.

List notifications for the authenticated user

List all notifications for the current user, sorted by most recently updated.

The following example uses the since parameter to list notifications that have been updated after the specified time.

octokit.activity.listNotificationsForAuthenticatedUser();

Parameters

See also: GitHub Developer Guide documentation.

List repository notifications for the authenticated user

Deprecated: This method has been renamed to activity.listRepoNotificationsForAuthenticatedUser

List all notifications for the current user.

octokit.activity.listNotificationsForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List organization events for the authenticated user

This is the user's organization dashboard. You must be authenticated as the user to view this.

octokit.activity.listOrgEventsForAuthenticatedUser({
  username,
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List public events

We delay the public events feed by five minutes, which means the most recent event returned by the public events API actually occurred at least five minutes ago.

octokit.activity.listPublicEvents();

Parameters

See also: GitHub Developer Guide documentation.

List public organization events

Deprecated: This method has been renamed to activity.listPublicOrgEvents

octokit.activity.listPublicEventsForOrg({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List public events for a network of repositories

octokit.activity.listPublicEventsForRepoNetwork({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List public events for a user

octokit.activity.listPublicEventsForUser({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

List public organization events

octokit.activity.listPublicOrgEvents({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List events received by the authenticated user

These are events that you've received by watching repos and following users. If you are authenticated as the given user, you will see private events. Otherwise, you'll only see public events.

octokit.activity.listReceivedEventsForUser({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

List public events received by a user

octokit.activity.listReceivedPublicEventsForUser({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

List repository events

octokit.activity.listRepoEvents({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List repository notifications for the authenticated user

List all notifications for the current user.

octokit.activity.listRepoNotificationsForAuthenticatedUser({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List repositories starred by the authenticated user

Lists repositories the authenticated user has starred.

You can also find out when stars were created by passing the following custom media type via the Accept header:

octokit.activity.listReposStarredByAuthenticatedUser();

Parameters

See also: GitHub Developer Guide documentation.

List repositories starred by a user

Lists repositories a user has starred.

You can also find out when stars were created by passing the following custom media type via the Accept header:

octokit.activity.listReposStarredByUser({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

List repositories watched by a user

Lists repositories a user is watching.

octokit.activity.listReposWatchedByUser({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

List stargazers

Lists the people that have starred the repository.

You can also find out when stars were created by passing the following custom media type via the Accept header:

octokit.activity.listStargazersForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

List repositories watched by the authenticated user

Lists repositories the authenticated user is watching.

octokit.activity.listWatchedReposForAuthenticatedUser();

Parameters

See also: GitHub Developer Guide documentation.

List watchers

Lists the people watching the specified repository.

octokit.activity.listWatchersForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Mark notifications as read

Deprecated: This method has been renamed to activity.markNotificationsAsRead

Marks all notifications as "read" removes it from the default view on GitHub. If the number of notifications is too large to complete in one request, you will receive a 202 Accepted status and GitHub will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List notifications for the authenticated user endpoint and pass the query parameter all=false.

octokit.activity.markAsRead();

Parameters

See also: GitHub Developer Guide documentation.

Mark notifications as read

Marks all notifications as "read" removes it from the default view on GitHub. If the number of notifications is too large to complete in one request, you will receive a 202 Accepted status and GitHub will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List notifications for the authenticated user endpoint and pass the query parameter all=false.

octokit.activity.markNotificationsAsRead();

Parameters

See also: GitHub Developer Guide documentation.

Mark repository notifications as read

Deprecated: This method has been renamed to activity.markRepoNotificationsAsRead

Marks all notifications in a repository as "read" removes them from the default view on GitHub. If the number of notifications is too large to complete in one request, you will receive a 202 Accepted status and GitHub will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List repository notifications for the authenticated user endpoint and pass the query parameter all=false.

octokit.activity.markNotificationsAsReadForRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Mark repository notifications as read

Marks all notifications in a repository as "read" removes them from the default view on GitHub. If the number of notifications is too large to complete in one request, you will receive a 202 Accepted status and GitHub will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List repository notifications for the authenticated user endpoint and pass the query parameter all=false.

octokit.activity.markRepoNotificationsAsRead({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Mark a thread as read

octokit.activity.markThreadAsRead({
  thread_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Set a repository subscription

If you would like to watch a repository, set subscribed to true. If you would like to ignore notifications made within a repository, set ignored to true. If you would like to stop watching a repository, delete the repository's subscription completely.

octokit.activity.setRepoSubscription({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Set a thread subscription

If you are watching a repository, you receive notifications for all threads by default. Use this endpoint to ignore future notifications for threads until you comment on the thread or get an @mention.

You can also use this endpoint to subscribe to threads that you are currently not receiving notifications for or to subscribed to threads that you have previously ignored.

Unsubscribing from a conversation in a repository that you are not watching is functionally equivalent to the Delete a thread subscription endpoint.

octokit.activity.setThreadSubscription({
  thread_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Star a repository for the authenticated user

Deprecated: This method has been renamed to activity.starRepoForAuthenticatedUser

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

octokit.activity.starRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Star a repository for the authenticated user

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

octokit.activity.starRepoForAuthenticatedUser({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Unstar a repository for the authenticated user

Deprecated: This method has been renamed to activity.unstarRepoForAuthenticatedUser

octokit.activity.unstarRepo({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Unstar a repository for the authenticated user

octokit.activity.unstarRepoForAuthenticatedUser({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Apps

Add repository to installation

Add a single repository to an installation. The authenticated user must have admin access to the repository.

You must use a personal access token (which you can create via the command line or the OAuth Authorizations API) or Basic Authentication to access this endpoint.

octokit.apps.addRepoToInstallation({
  installation_id,
  repository_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a subscription plan for an account

Deprecated: This method has been renamed to apps.getSubscriptionPlanForAccount

Shows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.checkAccountIsAssociatedWithAny({
  account_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a subscription plan for an account (stubbed)

Deprecated: This method has been renamed to apps.getSubscriptionPlanForAccountStubbed

Shows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.checkAccountIsAssociatedWithAnyStubbed({
  account_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Check a token

OAuth applications can use a special API method for checking OAuth token validity without exceeding the normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. You must use Basic Authentication to use this endpoint, where the username is the OAuth application client_id and the password is its client_secret. Invalid tokens will return 404 NOT FOUND.

octokit.apps.checkToken({
  client_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a content attachment

Creates an attachment under a content reference URL in the body or comment of an issue or pull request. Use the id of the content reference from the content_reference event to create an attachment.

The app must create a content attachment within six hours of the content reference URL being posted. See "Using content attachments" for details about content attachments.

You must use an installation access token to access this endpoint.

This example creates a content attachment for the domain https://errors.ai/.

octokit.apps.createContentAttachment({
  content_reference_id,
  title,
  body,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a GitHub App from a manifest

Use this endpoint to complete the handshake necessary when implementing the GitHub App Manifest flow. When you create a GitHub App with the manifest flow, you receive a temporary code used to retrieve the GitHub App's id, pem (private key), and webhook_secret.

octokit.apps.createFromManifest({
  code,
});

Parameters

See also: GitHub Developer Guide documentation.

Create a new installation token

Creates an installation access token that enables a GitHub App to make authenticated API requests for the app's installation on an organization or individual account. Installation tokens expire one hour from the time you create them. Using an expired token produces a status code of 401 - Unauthorized, and requires creating a new installation token. By default the installation token has access to all repositories that the installation can access. To restrict the access to specific repositories, you can provide the repository_ids when creating the token. When you omit repository_ids, the response does not contain the repositories key.

You must use a JWT to access this endpoint.

This example grants the token "Read and write" permission to issues and "Read" permission to contents, and restricts the token's access to the repository with an id of 1296269.

octokit.apps.createInstallationToken({
  installation_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete an app authorization

OAuth application owners can revoke a grant for their OAuth application and a specific user. You must use Basic Authentication when accessing this endpoint, using the OAuth application's client_id and client_secret as the username and password. You must also provide a valid OAuth access_token as an input parameter and the grant for the token's owner will be deleted.

Deleting an OAuth application's grant will also delete all OAuth tokens associated with the application for the user. Once deleted, the application will have no access to the user's account and will no longer be listed on the application authorizations settings screen within GitHub.

octokit.apps.deleteAuthorization({
  client_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete an installation

Uninstalls a GitHub App on a user, organization, or business account. If you prefer to temporarily suspend an app's access to your account's resources, then we recommend the "Suspend an installation" endpoint.

You must use a JWT to access this endpoint.

octokit.apps.deleteInstallation({
  installation_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Delete an app token

OAuth application owners can revoke a single token for an OAuth application. You must use Basic Authentication when accessing this endpoint, using the OAuth application's client_id and client_secret as the username and password.

octokit.apps.deleteToken({
  client_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get the authenticated GitHub App

Returns the GitHub App associated with the authentication credentials used. To see how many app installations are associated with this GitHub App, see the installations_count in the response. For more details about your app's installations, see the "List installations" endpoint.

You must use a JWT to access this endpoint.

octokit.apps.getAuthenticated();

Parameters

This endpoint has no parameters

See also: GitHub Developer Guide documentation.

Get a single GitHub App

Note: The :app_slug is just the URL-friendly name of your GitHub App. You can find this on the settings page for your GitHub App (e.g., https://github.com/settings/apps/:app_slug).

If the GitHub App you specify is public, you can access this endpoint without authenticating. If the GitHub App you specify is private, you must authenticate with a personal access token or an installation access token to access this endpoint.

octokit.apps.getBySlug({
  app_slug,
});

Parameters

See also: GitHub Developer Guide documentation.

Get an installation

You must use a JWT to access this endpoint.

octokit.apps.getInstallation({
  installation_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get an organization installation

Enables an authenticated GitHub App to find the organization's installation information.

You must use a JWT to access this endpoint.

octokit.apps.getOrgInstallation({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a repository installation

Enables an authenticated GitHub App to find the repository's installation information. The installation's account type will be either an organization or a user account, depending which account the repository belongs to.

You must use a JWT to access this endpoint.

octokit.apps.getRepoInstallation({
  owner,
  repo,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a subscription plan for an account

Shows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.getSubscriptionPlanForAccount({
  account_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a subscription plan for an account (stubbed)

Shows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.getSubscriptionPlanForAccountStubbed({
  account_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a user installation

Enables an authenticated GitHub App to find the user’s installation information.

You must use a JWT to access this endpoint.

octokit.apps.getUserInstallation({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

List accounts for a plan

Returns user and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.listAccountsForPlan({
  plan_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List accounts for a plan (stubbed)

Returns repository and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.listAccountsForPlanStubbed({
  plan_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List accounts for a plan

Deprecated: This method has been renamed to apps.listAccountsForPlan

Returns user and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.listAccountsUserOrOrgOnPlan({
  plan_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List accounts for a plan (stubbed)

Deprecated: This method has been renamed to apps.listAccountsForPlanStubbed

Returns repository and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.listAccountsUserOrOrgOnPlanStubbed({
  plan_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List repositories accessible to the user for an installation

List repositories that the authenticated user has explicit permission (:read, :write, or :admin) to access for an installation.

The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.

You must use a user-to-server OAuth access token, created for a user who has authorized your GitHub App, to access this endpoint.

The access the user has to each repository is included in the hash under the permissions key.

octokit.apps.listInstallationReposForAuthenticatedUser({
  installation_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List installations

You must use a JWT to access this endpoint.

The permissions the installation has are included under the permissions key.

octokit.apps.listInstallations();

Parameters

See also: GitHub Developer Guide documentation.

List installations for a user

Lists installations of your GitHub App that the authenticated user has explicit permission (:read, :write, or :admin) to access.

You must use a user-to-server OAuth access token, created for a user who has authorized your GitHub App, to access this endpoint.

The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.

You can find the permissions for the installation under the permissions key.

octokit.apps.listInstallationsForAuthenticatedUser();

Parameters

See also: GitHub Developer Guide documentation.

List subscriptions for the authenticated user

Deprecated: This method has been renamed to apps.listSubscriptionsForAuthenticatedUser

Lists the active subscriptions for the authenticated user. You must use a user-to-server OAuth access token, created for a user who has authorized your GitHub App, to access this endpoint. . OAuth Apps must authenticate using an OAuth token.

octokit.apps.listMarketplacePurchasesForAuthenticatedUser();

Parameters

See also: GitHub Developer Guide documentation.

List subscriptions for the authenticated user (stubbed)

Deprecated: This method has been renamed to apps.listSubscriptionsForAuthenticatedUserStubbed

Lists the active subscriptions for the authenticated user. You must use a user-to-server OAuth access token, created for a user who has authorized your GitHub App, to access this endpoint. . OAuth Apps must authenticate using an OAuth token.

octokit.apps.listMarketplacePurchasesForAuthenticatedUserStubbed();

Parameters

See also: GitHub Developer Guide documentation.

List plans

Lists all plans that are part of your GitHub Marketplace listing.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.listPlans();

Parameters

See also: GitHub Developer Guide documentation.

List plans (stubbed)

Lists all plans that are part of your GitHub Marketplace listing.

GitHub Apps must use a JWT to access this endpoint. OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

octokit.apps.listPlansStubbed();

Parameters

See also: GitHub Developer Guide documentation.

List repositories

List repositories that an installation can access.

You must use an installation access token to access this endpoint.

octokit.apps.listRepos();

Parameters

See also: GitHub Developer Guide documentation.

List subscriptions for the authenticated user

Lists the active subscriptions for the authenticated user. You must use a user-to-server OAuth access token, created for a user who has authorized your GitHub App, to access this endpoint. . OAuth Apps must authenticate using an OAuth token.

octokit.apps.listSubscriptionsForAuthenticatedUser();

Parameters

See also: GitHub Developer Guide documentation.

List subscriptions for the authenticated user (stubbed)

Lists the active subscriptions for the authenticated user. You must use a user-to-server OAuth access token, created for a user who has authorized your GitHub App, to access this endpoint. . OAuth Apps must authenticate using an OAuth token.

octokit.apps.listSubscriptionsForAuthenticatedUserStubbed();

Parameters

See also: GitHub Developer Guide documentation.

Remove repository from installation

Remove a single repository from an installation. The authenticated user must have admin access to the repository.

You must use a personal access token (which you can create via the command line or the OAuth Authorizations API) or Basic Authentication to access this endpoint.

octokit.apps.removeRepoFromInstallation({
  installation_id,
  repository_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Reset a token

OAuth applications can use this API method to reset a valid OAuth token without end-user involvement. Applications must save the "token" property in the response because changes take effect immediately. You must use Basic Authentication when accessing this endpoint, using the OAuth application's client_id and client_secret as the username and password. Invalid tokens will return 404 NOT FOUND.

octokit.apps.resetToken({
  client_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Revoke an installation token

Revokes the installation token you're using to authenticate as an installation and access this endpoint.

Once an installation token is revoked, the token is invalidated and cannot be used. Other endpoints that require the revoked installation token must have a new installation token to work. You can create a new token using the "Create a new installation token" endpoint.

You must use an installation access token to access this endpoint.

octokit.apps.revokeInstallationToken();

Parameters

This endpoint has no parameters

See also: GitHub Developer Guide documentation.

Suspend an installation

Note: Suspending a GitHub App installation is currently in beta and subject to change. Before you can suspend a GitHub App, the app owner must enable suspending installations for the app by opting-in to the beta. For more information, see "Suspending a GitHub App installation."

Suspends a GitHub App on a user, organization, or business account, which blocks the app from accessing the account's resources. When a GitHub App is suspended, the app's access to the GitHub API or webhook events is blocked for that account.

To suspend a GitHub App, you must be an account owner or have admin permissions in the repository or organization where the app is installed.

You must use a JWT to access this endpoint.

octokit.apps.suspendInstallation({
  installation_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Unsuspend an installation

Note: Suspending a GitHub App installation is currently in beta and subject to change. Before you can suspend a GitHub App, the app owner must enable suspending installations for the app by opting-in to the beta. For more information, see "Suspending a GitHub App installation."

Removes a GitHub App installation suspension.

To unsuspend a GitHub App, you must be an account owner or have admin permissions in the repository or organization where the app is installed and suspended.

You must use a JWT to access this endpoint.

octokit.apps.unsuspendInstallation({
  installation_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Checks

Create a check run

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

Creates a new check run for a specific commit in a repository. Your GitHub App must have the checks:write permission to create check runs.

octokit.checks.create({
        owner,
repo,
name,
head_sha,
output.title,
output.summary,
output.annotations[].path,
output.annotations[].start_line,
output.annotations[].end_line,
output.annotations[].annotation_level,
output.annotations[].message,
output.images[].alt,
output.images[].image_url,
actions[].label,
actions[].description,
actions[].identifier
      })

Parameters

See also: GitHub Developer Guide documentation.

Create a check suite

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

By default, check suites are automatically created when you create a check run. You only need to use this endpoint for manually creating check suites when you've disabled automatic creation using "Update repository preferences for check suites". Your GitHub App must have the checks:write permission to create check suites.

octokit.checks.createSuite({
  owner,
  repo,
  head_sha,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a check run

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

Gets a single check run using its id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the repo scope to get check runs in a private repository.

octokit.checks.get({
  owner,
  repo,
  check_run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Get a check suite

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

Gets a single check suite using its id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check suites. OAuth Apps and authenticated users must have the repo scope to get check suites in a private repository.

octokit.checks.getSuite({
  owner,
  repo,
  check_suite_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List check run annotations

Lists annotations for a check run using the annotation id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get annotations for a check run. OAuth Apps and authenticated users must have the repo scope to get annotations for a check run in a private repository.

octokit.checks.listAnnotations({
  owner,
  repo,
  check_run_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List check runs for a Git reference

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

Lists check runs for a commit ref. The ref can be a SHA, branch name, or a tag name. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the repo scope to get check runs in a private repository.

octokit.checks.listForRef({
  owner,
  repo,
  ref,
});

Parameters

See also: GitHub Developer Guide documentation.

List check runs in a check suite

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

Lists check runs for a check suite using its id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the repo scope to get check runs in a private repository.

octokit.checks.listForSuite({
  owner,
  repo,
  check_suite_id,
});

Parameters

See also: GitHub Developer Guide documentation.

List check suites for a Git reference

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

Lists check suites for a commit ref. The ref can be a SHA, branch name, or a tag name. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to list check suites. OAuth Apps and authenticated users must have the repo scope to get check suites in a private repository.

octokit.checks.listSuitesForRef({
  owner,
  repo,
  ref,
});

Parameters

See also: GitHub Developer Guide documentation.

Rerequest a check suite

Triggers GitHub to rerequest an existing check suite, without pushing new code to a repository. This endpoint will trigger the check_suite webhook event with the action rerequested. When a check suite is rerequested, its status is reset to queued and the conclusion is cleared.

To rerequest a check suite, your GitHub App must have the checks:read permission on a private repository or pull access to a public repository.

octokit.checks.rerequestSuite({
  owner,
  repo,
  check_suite_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Update repository preferences for check suites

Changes the default automatic flow when creating check suites. By default, the CheckSuiteEvent is automatically created each time code is pushed to a repository. When you disable the automatic creation of check suites, you can manually Create a check suite. You must have admin permissions in the repository to set preferences for check suites.

octokit.checks.setSuitesPreferences({
        owner,
repo,
auto_trigger_checks[].app_id,
auto_trigger_checks[].setting
      })

Parameters

See also: GitHub Developer Guide documentation.

Update a check run

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

Updates a check run for a specific commit in a repository. Your GitHub App must have the checks:write permission to edit check runs.

octokit.checks.update({
        owner,
repo,
check_run_id,
output.summary,
output.annotations[].path,
output.annotations[].start_line,
output.annotations[].end_line,
output.annotations[].annotation_level,
output.annotations[].message,
output.images[].alt,
output.images[].image_url,
actions[].label,
actions[].description,
actions[].identifier
      })

Parameters