Skip to main content

This version of GitHub Enterprise Server was discontinued on 2024-01-04. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Quickstart for GitHub REST API

Learn how to get started with the GitHub REST API.

Introduction

This article describes how to quickly get started with the GitHub REST API using GitHub CLI, curl, or JavaScript. For a more detailed guide, see "Getting started with the REST API."

Using GitHub CLI in the command line

GitHub CLI is the easiest way to use the GitHub REST API from the command line.

  1. Install GitHub CLI on macOS, Windows, or Linux. For more information, see Installation in the GitHub CLI repository.

  2. Authenticate with GitHub by running this command from your terminal. Replace HOSTNAME with the name of your GitHub Enterprise Server instance. For example, octo-inc.ghe.com.

    gh auth login --hostname HOSTNAME
    
  3. Follow the on-screen prompts.

    GitHub CLI automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your GitHub credentials. This can be useful as it allows you to use Git commands like git push and git pull without needing to set up a separate credential manager or use SSH.

  4. Make a request using the GitHub CLI api subcommand, followed by the path. Use the --method or -X flag to specify the method. For more information, see the GitHub CLI api documentation.

    This example makes a request to the "Get Octocat" endpoint, which uses the method GET and the path /octocat. For the full reference documentation for this endpoint, see "Meta."

    Shell
    gh api /octocat --method GET
    

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

Authenticating with an access token

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

The following example workflow uses the "List repository issues" endpoint, and requests a list of issues in a repository you specify. Replace HOSTNAME with the name of your GitHub 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.

YAML
on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

Authenticating with a GitHub App

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 API. For more information, see "GitHub Apps" in the REST API documentation. 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. In the following example, replace HOSTNAME with the name of your GitHub 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.

    YAML
    
    # 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 http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues
    

Next steps

For a more detailed guide, see "Getting started with the REST API."

Press alt+up to activate