Início Rápido para a API REST do GitHub

Introdução

Este artigo descreve como começar rapidamente com a API REST do GitHub usando a GitHub CLI, curl ou JavaScript. Para ver um guia mais detalhado, confira Introdução à API REST.

Como usar a GitHub CLI na linha de comando

A GitHub CLI é a maneira mais fácil de usar a API REST do GitHub por meio da linha de comando.

Instale a GitHub CLI no macOS, no Windows ou no Linux. Para obter instruções de instalação, confira Instalação no repositório do GitHub CLI.
Para se autenticar no GitHub, execute o comando a seguir no terminal.
```
gh auth login
```
Selecione o local em que deseja se autenticar:
- Se você acessar o GitHub no GitHub.com, selecione GitHub.com.
- Se você acessar o GitHub em um domínio diferente, selecione Outro e depois insira o nome do host (por exemplo, octocorp.ghe.com).
Siga o restante das solicitações na tela.

O GitHub CLI armazena automaticamente suas credenciais do Git quando você escolhe HTTPS como protocolo preferencial para operações Git e responde "sim" ao prompt que pergunta se deseja efetuar a autenticação no Git com suas credenciais do GitHub. Isso pode ser útil porque permite que você use comandos Git como git push e git pull sem a necessidade de configurar um gerenciador de credenciais separado ou usar SSH.
Faça uma solicitação usando o subcomando GitHub CLI api, seguido pelo caminho. Use o sinalizador --method ou -X para especificar o método. Para obter mais informações, confira a documentaçãoapi da GitHub CLI.

Este exemplo faz uma solicitação para o ponto de extremidade "Obter Octocat", que usa o método GET e o caminho /octocat. Para ver a documentação de referência completa desse ponto de extremidade, confira Pontos de extremidade da API REST para metadados.
Shell
```
gh api /octocat --method GET
```
```
gh api /octocat --method GET
```

Como usar a GitHub CLI em GitHub Actions

Você também pode usar a GitHub CLI em seus fluxos de trabalho de GitHub Actions. Para saber mais, confira Usar o GitHub CLI em fluxos de trabalho.

Autenticação com um token de acesso

Em vez de usar o comando gh auth login, passe um token de acesso como uma variável de ambiente chamada GH_TOKEN. O GitHub recomenda que você use o GITHUB_TOKEN interno em vez de criar um token. Se isso não for possível, armazene o token como um segredo e substitua GITHUB_TOKEN no exemplo abaixo pelo nome do seu segredo. Para obter mais informações sobre GITHUB_TOKEN, confira Autenticação automática de token. Para saber mais sobre segredos, confira Usar segredos em ações do GitHub.

O fluxo de trabalho de exemplo a seguir usa o ponto de extremidade Listar problemas do repositório e solicita uma lista de issues em um repositório que você especificar. Substitua o HOSTNAME pelo nome do sua instância do GitHub Enterprise Server. Substitua REPO-OWNER pelo nome da conta proprietária do repositório. Substitua REPO-NAME pelo nome do repositório.

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

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

Autenticação com um GitHub App

Se estiver se autenticando com um GitHub App, você poderá criar um token de acesso de instalação no fluxo de trabalho:

Armazene a ID do seu GitHub App como uma variável de configuração. No exemplo a seguir, substitua APP_ID pelo nome da variável de configuração. Você pode encontrar o ID do aplicativo na página de configurações do aplicativo ou por meio da API. Para saber mais, confira Pontos de extremidade da API REST para o GitHub Apps. Para saber mais sobre variáveis de configuração, confira Armazenar informações em variáveis.
Gerar uma chave privada para o seu aplicativo. Armazene o conteúdo do arquivo resultante como um segredo. (Armazene todo o conteúdo do arquivo, incluindo -----BEGIN RSA PRIVATE KEY----- e -----END RSA PRIVATE KEY-----). No exemplo a seguir, substitua APP_PEM pelo nome do segredo. Para saber mais, confira Como gerenciar chaves privadas para Aplicativos GitHub. Para saber mais sobre segredos, confira Usar segredos em ações do GitHub.

Adicione uma etapa para gerar um token e use esse token em vez de GITHUB_TOKEN. Observe que esse token vai expirar após 60 minutos. no exemplo a seguir, substitua HOSTNAME pelo nome do sua instância do GitHub Enterprise Server. Substitua REPO-OWNER pelo nome da conta proprietária do repositório. Substitua REPO-NAME pelo nome do repositório.

YAML

on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.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


on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.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

Como usar Octokit.js

Você pode usar Octokit.js para interagir com a API REST do GitHub em seus scripts do JavaScript. Para obter mais informações, confira Scripts com a API REST e o JavaScript.

Crie um token de acesso. Por exemplo, crie um personal access token ou um token de acesso de usuário do GitHub App. Você usará esse token para autenticar sua solicitação, portanto, você deve conceder a ele todos os escopos ou permissões necessários para acessar esse ponto de extremidade. Para obter mais informações, confira Autenticação na API REST ou Como identificar e autorizar usuários para Aplicativos do GitHub.

Warning

Trate o token de acesso como faria com uma senha.

Para manter seu token seguro, você pode armazená-lo como um segredo e executar seu script por meio de GitHub Actions. Para obter mais informações, confira a seção Como usar o Octokit.js em GitHub Actions.

Se essas opções não forem possíveis, considere usar outro serviço de CLI para armazenar seu token com segurança.
Instale o octokit. Por exemplo, npm install octokit. Para outras maneiras de instalar ou carregar octokit, confira o LEIA-ME do Octokit.js.
Importe octokit em seu script. Por exemplo, import { Octokit } from "octokit";. Para outras maneiras de importar octokit, confira o LEIA-ME do Octokit.js.

Crie uma instância do Octokit com o seu token. Substitua HOSTNAME pelo nome do sua instância do GitHub Enterprise Server. Substitua YOUR-TOKEN pelo seu token.

JavaScript

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

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

Use octokit.request para executar sua solicitação. Envie o método HTTP e o caminho como o primeiro argumento. Especifique quaisquer parâmetros de caminho, consulta e corpo em um objeto como o segundo argumento. Para obter mais informações sobre parâmetros, confira Introdução à API REST.

Por exemplo, na solicitação a seguir, o método HTTP é GET, o caminho é /repos/{owner}/{repo}/issues e os parâmetros são owner: "REPO-OWNER" e repo: "REPO-NAME". Substitua REPO-OWNER pelo nome da conta proprietária do repositório e REPO-NAME pelo nome do repositório.
JavaScript
```
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "REPO-OWNER",
  repo: "REPO-NAME",
});
```
```
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "REPO-OWNER",
  repo: "REPO-NAME",
});
```

Como usar o Octokit.js em GitHub Actions

Você também pode executar seus scripts do JavaScript nos fluxos de trabalho de GitHub Actions. Para saber mais, confira Sintaxe de fluxo de trabalho para o GitHub Actions.

Autenticação com um token de acesso

O GitHub recomenda que você use o GITHUB_TOKEN interno em vez de criar um token. Se isso não for possível, armazene o token como um segredo e substitua GITHUB_TOKEN no exemplo abaixo pelo nome do seu segredo. Para obter mais informações sobre GITHUB_TOKEN, confira Autenticação automática de token. Para saber mais sobre segredos, confira Usar segredos em ações do GitHub.

O seguinte exemplo de fluxo de trabalho:

Verifica o conteúdo do repositório
Configura o Node.js
Instala octokit
Armazena o valor de GITHUB_TOKEN como uma variável de ambiente chamada de TOKEN e executa .github/actions-scripts/use-the-api.mjs, que pode acessar essa variável de ambiente como process.env.TOKEN

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@v4
        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 }}

Veja a seguir um exemplo de script do JavaScript com o caminho de arquivo .github/actions-scripts/use-the-api.mjs. Substitua HOSTNAME pelo nome de sua instância do GitHub Enterprise Server. Substitua REPO-OWNER pelo nome da conta proprietária do repositório. Substitua REPO-NAME pelo nome do repositório.

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}`)
}

Autenticação com um GitHub App

Se estiver se autenticando com um GitHub App, você poderá criar um token de acesso de instalação no fluxo de trabalho:

Armazene a ID do seu GitHub App como uma variável de configuração. No exemplo a seguir, substitua APP_ID pelo nome da variável de configuração. Você pode encontrar o ID do seu aplicativo na página de configurações do seu aplicativo ou por meio da API do aplicativo. Para saber mais, confira Pontos de extremidade da API REST para o GitHub Apps. Para saber mais sobre variáveis de configuração, confira Armazenar informações em variáveis.
Gerar uma chave privada para o seu aplicativo. Armazene o conteúdo do arquivo resultante como um segredo. (Armazene todo o conteúdo do arquivo, incluindo -----BEGIN RSA PRIVATE KEY----- e -----END RSA PRIVATE KEY-----). No exemplo a seguir, substitua APP_PEM pelo nome do segredo. Para saber mais, confira Como gerenciar chaves privadas para Aplicativos GitHub. Para saber mais sobre segredos, confira Usar segredos em ações do GitHub.

Adicione uma etapa para gerar um token e use esse token em vez de GITHUB_TOKEN. Observe que esse token vai expirar após 60 minutos. Por exemplo:


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@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-github-app-token@v1
        with:
          app-id: ${{ vars.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 }}

Como usar `curl` na linha de comando

Note

Se você quiser fazer solicitações de API usando a linha de comando, o GitHub recomenda o uso da GitHub CLI, o que simplifica a autenticação e as solicitações. Para obter mais informações sobre como começar a usar a API REST usando a GitHub CLI, confira a versão da GitHub CLI deste artigo.

Instale o curl caso ainda não o tenha feito em seu computador. Para verificar se o curl está instalado, execute curl --version na linha de comando. Se a saída fornecer informações sobre a versão do curl, isso significará que o curl está instalado. Se você receber uma mensagem semelhante a command not found: curl, será necessário baixar e instalar o curl. Para obter mais informações, confira a página de download do projeto curl.
Crie um token de acesso. Por exemplo, crie um personal access token ou um token de acesso de usuário do GitHub App. Você usará esse token para autenticar sua solicitação, portanto, você deve conceder a ele todos os escopos ou permissões necessários para acessar o ponto de extremidade. Para saber mais, confira Autenticação na API REST.

Warning

Trate o token de acesso como faria com uma senha.

Você também pode usar a GitHub CLI em vez do curl. A GitHub CLI cuidará da autenticação para você. Para obter mais informações, confira a versão da GitHub CLI desta página.

Se essas opções não forem possíveis, considere usar outro serviço do CLI para armazenar seu token com segurança.
Use o comando curl para fazer sua solicitação. Passe o seu token em um cabeçalho de Authorization Substitua HOSTNAME pelo nome do sua instância do GitHub Enterprise Server. Substitua REPO-OWNER pelo nome da conta proprietária do repositório. Substitua REPO-NAME pelo nome do repositório. Substitua YOUR-TOKEN pelo seu token.
Shell
```
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
```
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
Note

Na maioria dos casos, você pode usar Authorization: Bearer ou Authorization: token a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usar Authorization: Bearer.

Como usar os comandos `curl` em GitHub Actions

Você também pode usar os comandos curl em seus fluxo de trabalho de GitHub Actions.

Autenticação com um token de acesso

O GitHub recomenda que você use o GITHUB_TOKEN interno em vez de criar um token. Se isso não for possível, armazene o token como um segredo e substitua GITHUB_TOKEN no exemplo abaixo pelo nome do seu segredo. Para obter mais informações sobre GITHUB_TOKEN, confira Autenticação automática de token. Para saber mais sobre segredos, confira Usar segredos em ações do GitHub.

No exemplo a seguir, substitua HOSTNAME pelo nome do sua instância do GitHub Enterprise Server. Substitua REPO-OWNER pelo nome da conta proprietária do repositório. Substitua REPO-NAME pelo nome do repositório.

YAML

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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

Autenticação com um GitHub App

Se estiver se autenticando com um GitHub App, você poderá criar um token de acesso de instalação no fluxo de trabalho:

Armazene a ID do seu GitHub App como uma variável de configuração. No exemplo a seguir, substitua APP_ID pelo nome da variável de configuração. Você pode encontrar o ID do seu aplicativo na página de configurações do seu aplicativo ou por meio da API do aplicativo. Para saber mais, confira Pontos de extremidade da API REST para o GitHub Apps. Para saber mais sobre variáveis de configuração, confira Armazenar informações em variáveis.
Gerar uma chave privada para o seu aplicativo. Armazene o conteúdo do arquivo resultante como um segredo. (Armazene todo o conteúdo do arquivo, incluindo -----BEGIN RSA PRIVATE KEY----- e -----END RSA PRIVATE KEY-----). No exemplo a seguir, substitua APP_PEM pelo nome do segredo. Para saber mais, confira Como gerenciar chaves privadas para Aplicativos GitHub. Para saber mais sobre como armazenar segredos, confira Usar segredos em ações do GitHub.

Adicione uma etapa para gerar um token e use esse token em vez de GITHUB_TOKEN. Observe que esse token vai expirar após 60 minutos. no exemplo a seguir, substitua HOSTNAME pelo nome do sua instância do GitHub Enterprise Server. Substitua REPO-OWNER pelo nome da conta proprietária do repositório. Substitua REPO-NAME pelo nome do repositório.

YAML

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}

      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"


on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}

      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

Próximas etapas

Para obter um guia mais detalhado, confira Introdução à API REST.

Início Rápido para a API REST do GitHub

Tool navigation

Neste artigo

Introdução

Como usar a GitHub CLI na linha de comando

Como usar a GitHub CLI em GitHub Actions

Autenticação com um token de acesso

Autenticação com um GitHub App

Como usar Octokit.js

Como usar o Octokit.js em GitHub Actions

Autenticação com um token de acesso

Autenticação com um GitHub App

Como usar `curl` na linha de comando

Como usar os comandos `curl` em GitHub Actions

Autenticação com um token de acesso

Autenticação com um GitHub App

Próximas etapas