Scripting with the REST API and JavaScript

About Octokit.js

If you want to write a script using JavaScript to interact with GitHub's REST API, GitHub recommends that you use the Octokit.js SDK. Octokit.js is maintained by GitHub. The SDK implements best practices and makes it easier for you to interact with the REST API via JavaScript. Octokit.js works with all modern browsers, Node.js, and Deno. For more information about Octokit.js, see the Octokit.js README.

Prerequisites

This guide assumes that you are familiar with JavaScript and the GitHub REST API. For more information about the REST API, see Getting started with the REST API.

You must install and import octokit in order to use the Octokit.js library. This guide uses import statements in accordance with ES6. For more information about different installation and import methods, see the Octokit.js README's Usage section.

Instantiating and authenticating

If this is not possible, consider using another CLI service to store your credentials securely.

Authenticating with a personal access token

If you want to use the GitHub REST API for personal use, you can create a personal access token. For more information about creating a personal access token, see Managing your personal access tokens.

First, import Octokit from octokit. Then, pass your personal access token when you create an instance of Octokit. In the following example, replace YOUR-TOKEN with a reference to your personal access token. Replace HOSTNAME with the name of your GitHub Enterprise Server instance.

import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN',
});

import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN',
});

Authenticating with a GitHub App

If you want to use the API on behalf of an organization or another user, GitHub recommends that you use a GitHub App. If an endpoint is available to GitHub Apps, the REST reference documentation for that endpoint will indicate what type of GitHub App token is required. For more information, see Registering a GitHub App and About authentication with a GitHub App.

Instead of importing Octokit from octokit, import App. In the following example, replace APP_ID with a reference to your app's ID. Replace PRIVATE_KEY with a reference to your app's private key. Replace INSTALLATION_ID with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see Managing private keys for GitHub Apps. You can get an installation ID with the GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, or GET /orgs/{org}/installation endpoints. For more information, see REST API endpoints for GitHub Apps. Replace HOSTNAME with the name of your GitHub Enterprise Server instance.

import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  Octokit: Octokit.defaults({
    baseUrl: "http(s)://HOSTNAME/api/v3",
  }),
});

const octokit = await app.getInstallationOctokit(INSTALLATION_ID);

import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  Octokit: Octokit.defaults({
    baseUrl: "http(s)://HOSTNAME/api/v3",
  }),
});

const octokit = await app.getInstallationOctokit(INSTALLATION_ID);

Authenticating in GitHub Actions

If you want to use the API in a GitHub Actions workflow, GitHub recommends that you authenticate with the built-in GITHUB_TOKEN instead of creating a token. You can grant permissions to the GITHUB_TOKEN with the permissions key. For more information about GITHUB_TOKEN, see Automatic token authentication.

If your workflow needs to access resources outside of the workflow's repository, then you will not be able to use GITHUB_TOKEN. In that case, store your credentials as a secret and replace GITHUB_TOKEN in the examples below with the name of your secret. For more information about secrets, see Using secrets in GitHub Actions.

If you use the run keyword to execute your JavaScript script in your GitHub Actions workflows, you can store the value of GITHUB_TOKEN as an environment variable. Your script can access the environment variable as process.env.VARIABLE_NAME.

For example, this workflow step stores GITHUB_TOKEN in an environment variable called TOKEN:

-