Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais atualizadas, acesse a documentação em inglês.

Esta versão do GitHub Enterprise será descontinuada em 2023-03-15. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

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

Saiba como começar a usar a API REST do GitHub.

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

Introdução ao uso da GitHub CLI

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.

  1. Instale a GitHub CLI caso ainda não o tenha feito. Para obter instruções de instalação, confira o repositório da GitHub CLI.

  2. Use o subcomando auth login para se autenticar na GitHub CLI. Para obter mais informações, confira a documentaçãoauth login da GitHub CLI.

    gh auth login
  3. Use o subcomando api para fazer sua solicitação de API. Para obter mais informações, confira a documentaçãoapi da GitHub CLI.

    gh api repos/octocat/Spoon-Knife/issues

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 obter mais informações, confira "Como usar a CLI do GitHub em fluxos de trabalho".

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 a "Autenticação automática de token". Para obter mais informações sobre segredos, confira "Segredos criptografados".

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

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

  1. Armazene a ID do seu GitHub App como um segredo. No exemplo a seguir, substitua APP_ID pelo nome do segredo. Você pode encontrar o ID do aplicativo na página de configurações do aplicativo ou por meio da API. Para obter mais informações, consulte "Aplicativos" na documentação da API REST. Para obter mais informações sobre segredos, confira "Segredos criptografados".
  2. 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 obter mais informações, confira "Autenticação com os GitHub Apps".
  3. 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:
# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.

on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        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

Introdução ao uso do JavaScript

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

Como usar Octokit.js

  1. Crie um token de acesso. Por exemplo, crie um personal access token ou um token de acesso usuário para servidor do GitHub App. Para obter mais informações, confira "Como criar um personal access token" ou "Como identificar e autorizar usuários para Aplicativos GitHub".

    Aviso: trate seu token de acesso como 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, como a CLI do 1Password, para armazenar seu token com segurança.

  2. Instale o octokit. Por exemplo, npm install octokit. Para outras maneiras de instalar ou carregar octokit, confira o LEIA-ME do Octokit.js.

  3. Importe octokit em seu script. Por exemplo, import { Octokit } from "octokit";. Para outras maneiras de importar octokit, confira o LEIA-ME do Octokit.js.

  4. Crie uma instância de Octokit com seu token. Substitua YOUR-TOKEN pelo seu token.

    const octokit = new Octokit({
      auth: 'YOUR-TOKEN'
    });
    
  5. 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. 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: "octocat" e repo: "Spoon-Knife".

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

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 obter mais informações, confira "Sintaxe de fluxo de trabalho do GitHub Actions".

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 a "Autenticação automática de token". Para obter mais informações sobre segredos, confira "Segredos criptografados".

O seguinte exemplo de fluxo de trabalho:

  1. Verifica o conteúdo do repositório
  2. Configura o Node.js
  3. Instala octokit
  4. 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

Fluxo de trabalho de exemplo:

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

      - name: Setup Node
        uses: actions/setup-node@v2
        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 }}

Exemplo de script do JavaScript, com o caminho do arquivo .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}`)
}

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

  1. Armazene a ID do seu GitHub App como um segredo. No exemplo a seguir, substitua APP_ID pelo nome do segredo. 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 obter mais informações, confira "Aplicativos". Para obter mais informações sobre segredos, confira "Segredos criptografados".
  2. 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 obter mais informações, confira "Autenticação com os GitHub Apps".
  3. 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:
# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repo content
        uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v2
        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@36464acb844fc53b9b8b2401da68844f6b05ebb0
        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 }}

Introdução ao uso de curl

Como usar curl na linha de comando

Observação: se você quiser fazer solicitações de API da linha de comando, o GitHub recomenda que você use 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.

  1. 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 for correspondente às informações sobre a versão do curl, ele será 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.

  2. Crie um token de acesso. Por exemplo, crie um personal access token ou um token de acesso usuário para servidor do GitHub App. Para obter mais informações, confira "Como criar um personal access token" ou "Como identificar e autorizar usuários para Aplicativos GitHub".

    Aviso: trate seu token de acesso como 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, como a CLI do 1Password, para armazenar seu token com segurança.

  3. Use o comando curl para fazer sua solicitação. Passe o token em um cabeçalho Authorization. Substitua YOUR-TOKEN pelo seu token.

    curl --request GET \
    --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer YOUR-TOKEN"

    Observação: 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.

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 a "Autenticação automática de token". Para obter mais informações sobre segredos, confira "Segredos criptografados".

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"

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

  1. Armazene a ID do seu GitHub App como um segredo. No exemplo a seguir, substitua APP_ID pelo nome do segredo. 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 obter mais informações, confira "Aplicativos". Para obter mais informações sobre segredos, confira "Segredos criptografados".
  2. 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 obter mais informações, confira "Autenticação com os GitHub Apps".
  3. 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:
# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.APP_PEM }}

      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate_token.outputs.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"

Próximas etapas

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