Quickstart for GitHub REST API

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api repos/octocat/Spoon-Knife/issues

Getting started using JavaScript

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

Using Octokit.js

1. Create an access token. For example, create a personal access token or a GitHub App user access token. For more information, see "Creating a personal access token" or "Identifying and authorizing users for GitHub 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 GitHub Actions. For more information, see the "Using Octokit.js in GitHub 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 YOUR-TOKEN with your token.

   const octokit = new Octokit({
     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 example, in the following request the HTTP method is GET, the path is /repos/{owner}/{repo}/issues, and the parameters are owner: "octocat" and repo: "Spoon-Knife".

   await octokit.request("GET /repos/{owner}/{repo}/issues", {
     owner: "octocat",
     repo: "Spoon-Knife",
   });
   

Using Octokit.js in GitHub Actions

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

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

The following example workflow:

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

Example workflow:

on:
  workflow_dispatch:
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@v3
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

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

Example JavaScript script, with the file path .github/actions-scripts/use-the-api.mjs:

import { Octokit } from "octokit"

const octokit = new Octokit({
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "octocat",
      repo: "Spoon-Knife",
    });

  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 GitHub App, you can create an installation access token within your workflow:

1. Store your GitHub App's ID as a secret. In the following example, replace APP_ID with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "GitHub Apps." For more information about secrets, see "Using secrets in GitHub Actions."

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 GitHub Apps."

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

   
   # This workflow uses actions that are not certified by GitHub.
   # They are provided by a third-party and are governed by
   # separate terms of service, privacy policy, and support
   # documentation.
   
   # GitHub recommends pinning actions to a commit SHA.
   # To get a newer version, you will need to update the SHA.
   # You can also reference a tag or branch, but the action may change without warning.
   
   on:
     workflow_dispatch:
   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@v3
           with:
             node-version: '16.17.0'
             cache: npm
   
         - name: Install dependencies
           run: npm install octokit
   
         - name: Generate token
           id: generate_token
           uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92
           with:
             app_id: ${{ secrets.APP_ID }}
             private_key: ${{ secrets.APP_PEM }}
   
         - name: Run script
           run: |
             node .github/actions-scripts/use-the-api.mjs
           env:
             TOKEN: ${{ steps.generate_token.outputs.token }}
   
   

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"