Quickstart for REST API

You can use Octokit.js to interact with the REST API in your JavaScript scripts. For more information, see Scripting with the REST API and JavaScript.

1. Create an access token. For example, create a personal access token or a App user access token. You will use this token to authenticate your request, so you should give it any scopes or permissions that are required to access that endpoint. For more information, see Authenticating to the REST API or Identifying and authorizing users for Apps.

   Warning

   Treat your access token like a password.

   To keep your token secure, you can store your token as a secret and run your script through Actions. For more information, see the Using Octokit.js in Actions section.

   If these options are not possible, consider using another CLI service to store your token securely.

2. Install octokit. For example, npm install octokit. For other ways to install or load octokit, see the Octokit.js README.

3. Import octokit in your script. For example, import { Octokit } from "octokit";. For other ways to import octokit, see the Octokit.js README.

4. Create an instance of Octokit with your token. Replace HOSTNAME with the name of your Enterprise Server instance. Replace YOUR-TOKEN with your token.

   JavaScript

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

5. Use octokit.request to execute your request. Send the HTTP method and path as the first argument. Specify any path, query, and body parameters in an object as the second argument. For more information about parameters, see Getting started with the REST API.

   For example, in the following request the HTTP method is GET, the path is /repos/{owner}/{repo}/issues, and the parameters are owner: "REPO-OWNER" and repo: "REPO-NAME". Replace REPO-OWNER with the name of the account that owns the repository, and REPO-NAME with the name of the repository.

   JavaScript

   await octokit.request("GET /repos/{owner}/{repo}/issues", {
     owner: "REPO-OWNER",
     repo: "REPO-NAME",
   });
   

You can also execute your JavaScript scripts in your Actions workflows. For more information, see Workflow syntax for Actions.

recommends that you use the built-in _TOKEN instead of creating a token. If this is not possible, store your token as a secret and replace _TOKEN in the example below with the name of your secret. For more information about _TOKEN, see Automatic token authentication. For more information about secrets, see Using secrets in Actions.

The following example workflow:

1. Checks out the repository content
2. Sets up Node.js
3. Installs octokit
4. Stores the value of _TOKEN as an environment variable called TOKEN and runs ./actions-scripts/use-the-api.mjs, which can access that environment variable as process.env.TOKEN

on:
  workflow_dis:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - name: Check out repo content
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        run: |
          node ./actions-scripts/use-the-api.mjs
        env:
          TOKEN: ${{ secrets._TOKEN }}

The following is an example JavaScript script with the file path ./actions-scripts/use-the-api.mjs. Replace HOSTNAME with the name of your Enterprise Server instance. Replace REPO-OWNER with the name of the account that owns the repository. Replace REPO-NAME with the name of the repository.

import { Octokit } from "octokit"

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "REPO-OWNER",
      repo: "REPO-NAME",
    });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

If you are authenticating with a App, you can create an installation access token within your workflow:

1. Store your App's ID as a configuration variable. In the following example, replace APP_ID with the name of the configuration variable. You can find your app ID on the settings page for your app or through the App API. For more information, see REST API endpoints for Apps. For more information about configuration variables, see Store information in variables.

2. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----.) In the following example, replace APP_PEM with the name of the secret. For more information, see Managing private keys for Apps. For more information about secrets, see Using secrets in Actions.

3. Add a step to generate a token, and use that token instead of _TOKEN. Note that this token will expire after 60 minutes. For example:

   on:
     workflow_dis:
   jobs:
     use_api_via_script:
       runs-on: ubuntu-latest
       steps:
         - name: Check out repo content
           uses: actions/checkout@v4
   
         - name: Setup Node
           uses: actions/setup-node@v4
           with:
             node-version: '16.17.0'
             cache: npm
   
         - name: Install dependencies
           run: npm install octokit
   
         - name: Generate token
           id: generate-token
           uses: actions/create--app-token@v1
           with:
             app-id: ${{ vars.APP_ID }}
             private-key: ${{ secrets.APP_PEM }}
   
         - name: Run script
           run: |
             node ./actions-scripts/use-the-api.mjs
           env:
             TOKEN: ${{ steps.generate-token.outputs.token }}