This article describes how to quickly get started with the GitHub REST API using GitHub CLI, JavaScript, or curl
. For a more detailed guide, see "Getting started with the REST API."
Getting started using GitHub CLI
Using GitHub CLI in the command line
GitHub CLI is the easiest way to use the GitHub REST API from the command line.
Note: The following example is intended for GitHub.com. If you'd prefer to try the example using GitHub Enterprise Server, you must replace octocat/Spoon-Knife
with a repository on your instance. Alternatively, rerun the gh auth login
command to authenticate to GitHub.com instead of your instance.
-
Install GitHub CLI if you haven't installed it yet. For installation instructions, see the GitHub CLI repository.
-
Use the
auth login
subcommand to authenticate to GitHub CLI. For more information, see the GitHub CLIauth login
documentation.gh auth login
-
Use the
api
subcommand to make your API request. For more information, see the GitHub CLIapi
documentation.gh api repos/octocat/Spoon-Knife/issues
Using GitHub CLI in GitHub Actions
You can also use GitHub CLI in your GitHub Actions workflows. For more information, see "Using GitHub CLI in workflows."
Instead of using the gh auth login
command, pass an access token as an environment variable called GH_TOKEN
. 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."
Note: The following example workflows are intended for GitHub.com. If you'd prefer to try the examples using GitHub Enterprise Server, you must replace octocat/Spoon-Knife
with a repository on GitHub Enterprise Server.
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
If you are authenticating with a GitHub App, you can create an installation access token within your workflow:
-
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 API. For more information, see "GitHub Apps" in the REST API documentation. For more information about secrets, see "Using secrets in GitHub Actions." -
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, replaceAPP_PEM
with the name of the secret. For more information, see "Managing private keys for GitHub Apps." -
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: track_pr: runs-on: ubuntu-latest steps: - name: Generate token id: generate_token uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92 with: app_id: ${{ secrets.APP_ID }} private_key: ${{ secrets.APP_PEM }} - name: Use API env: GH_TOKEN: ${{ steps.generate_token.outputs.token }} run: | gh api repos/octocat/Spoon-Knife/issues
Next steps
For a more detailed guide, see "Getting started with the REST API."