Início Rápido da API REST GitHub

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

Tool navigation

Neste artigo

Introdução

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

Como usar GitHub CLI na linha de comando

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

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

  2. Para se autenticar no GitHub, execute o comando a seguir no terminal.

    gh auth login

  3. 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).

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

  5. Faça uma solicitação usando o GitHub CLIapi subcomando, seguido pelo caminho. Use o sinalizador --method ou -X para especificar o método. Para obter mais informações, consulte a GitHub CLIapi documentação.

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

    Shell
    gh api /octocat --method GET

Usando GitHub CLI em GitHub Actions

Você também pode usar GitHub CLI em seus GitHub Actions fluxos de trabalho. Para saber mais, confira Usando 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. GitHub recomenda que você use o GITHUB_TOKEN integrado 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 Usar GITHUB_TOKEN para autenticação em fluxos de trabalho. 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 de repositório e solicita uma lista de problemas que octocat/Spoon-Knifevocê especificar.

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

Autenticando com um GitHub App

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

  1. Armazene o ID do cliente de GitHub App como uma variável de configuração. No exemplo a seguir, substitua APP_CLIENT_ID pelo nome da variável de configuração. Você pode encontrar sua ID do cliente 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.

  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_PRIVATE_KEY pelo nome do segredo. Para saber mais, confira Gerenciando chaves privadas para aplicativos GitHub. Para saber mais sobre segredos, confira Usar segredos em ações do GitHub.

  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:

    YAML
    on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v3
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api https://api.github.com/repos/octocat/Spoon-Knife/issues

Como usar Octokit.js

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

  1. Crie um token de acesso. Por exemplo, crie um personal access token ou um GitHub App token de acesso do usuário. Você usará esse token para autenticar sua solicitação, então deve conceder a ele todos os escopos ou permissões necessários para acessar esse endpoint. Para obter mais informações, consulte Autenticação na API REST ou Identificando e autorizando usuários para aplicativos do GitHub.

    Aviso

    Trate o token de acesso como faria com uma senha.

    Para manter seu token seguro, você pode armazenar seu token como segredo e executar seu script por meio de GitHub Actions. Para obter mais informações, consulte a seção Usando Octokit.js.GitHub Actions

    Você também pode armazenar seu token como um Codespaces segredo e executar seu script em Codespaces. Para obter mais informações, confira Como gerenciar segredos criptografados para seus codespaces.

    Se essas opções não forem possíveis, considere usar outro serviço de CLI para armazenar seu token com segurança.

  2. Instale octokit. Por exemplo, npm install octokit. Para outras formas de instalar ou carregar octokit, consulte o README do Octokit.js.

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

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

    JavaScript
    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. 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ãoowner: "octocat"``repo: "Spoon-Knife"

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

Usando Octokit.js em GitHub Actions

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

Autenticação com um token de acesso

GitHub recomenda que você use o GITHUB_TOKEN integrado 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 Usar GITHUB_TOKEN para autenticação em fluxos de trabalho. Para saber mais sobre segredos, confira Usar segredos em ações do GitHub.

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
on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - name: Check out repo content