Carregando
0xC0Lição 13 de 14

A CLI gh e a API do GitHub

Comande o GitHub pelo terminal com o gh e automatize-o com as APIs REST e GraphQL, paginação, limites de requisições e webhooks.

26 min Questionário com 7 perguntas 2 exercícios de código
Ao final desta lição, você saberá
  • Usar a CLI gh para pull requests, issues, execuções e releases
  • Chamar a API REST com autenticação e tratar paginação e limites de requisições
  • Escolher entre REST, GraphQL e webhooks para uma automação

Tudo o que você clicou nesta trilha pode ser feito pelo terminal com o gh, a CLI oficial do GitHub - e virar script pela API. Mantenedores que vivem no terminal economizam horas por semana.

a day in the terminal
1gh auth login                              # sign in once (stores a token securely)
2gh repo clone dungeon-dash/dungeon-dash
3gh issue list --label "good first issue"
4gh issue create --title "Boss music too loud" --label bug
5gh pr checkout 128                         # check out someone's PR locally to test it
6gh pr review 128 --approve --body "Played it - the dragon is great!"
7gh pr checks 128                           # CI status
8gh run watch                               # follow a running workflow live
9gh run rerun --failed                      # re-run failed jobs
10gh api repos/dungeon-dash/dungeon-dash/releases/latest --jq .tag_name

A API REST

A API REST fica em https://api.github.com. Cada recurso tem uma URL - /repos/OWNER/REPO/issues, /repos/OWNER/REPO/pulls/128, /users/mira - e devolve JSON. Autentique-se com um token num cabeçalho (Authorization: Bearer TOKEN); o gh api faz isso por você.

Duas coisas que todo script de API precisa tratar:

  • Paginação. As listas vêm em páginas (30 itens por padrão, até 100 com per_page=100). O cabeçalho de resposta Link dá as URLs das páginas next e last - siga a next até não haver mais. (gh api --paginate faz isso automaticamente.)
  • Limites de requisições. Requisições autenticadas têm 5.000 por hora (sem autenticação: 60). Os cabeçalhos x-ratelimit-remaining e x-ratelimit-reset dizem onde você está - diminua o ritmo quando chegar perto.
pagination.py
1import re
2
3link_header = (
4    '<https://api.github.com/repos/dungeon-dash/dungeon-dash/issues?page=2>; rel="next", '
5    '<https://api.github.com/repos/dungeon-dash/dungeon-dash/issues?page=14>; rel="last"'
6)
7links = {rel: url for url, rel in re.findall(r'<([^>]+)>;\s*rel="(\w+)"', link_header)}
8print("next:", links["next"])
9print("pages:", re.search(r"[?&]page=(\d+)", links["last"]).group(1))
Saída
next: https://api.github.com/repos/dungeon-dash/dungeon-dash/issues?page=2
pages: 14

GraphQL e webhooks

  • A API GraphQL (https://api.github.com/graphql) deixa uma única requisição pedir exatamente os campos de que você precisa em objetos relacionados - “os últimos 10 PRs com as revisões e os resultados das verificações” - em vez de muitas chamadas REST.
  • Os webhooks invertem a direção: em vez de perguntar ao GitHub de novo e de novo (“já tem issue nova?”), o GitHub envia um HTTP POST para o seu servidor quando algo acontece - uma issue aberta, um PR mesclado, uma release publicada. Verifique o cabeçalho de assinatura de cada entrega com o secret do seu webhook.
  • Para automações que devem morar dentro do repositório, um workflow do GitHub Actions escutando os mesmos eventos costuma ser o mais simples; para um serviço que atua em muitos repositórios, construa um GitHub App com permissões fine-grained.

Experimente

Até 15 XP

Que ferramenta para cada trabalho?

Escolha a melhor opção para cada automação.

0 de 6 classificadosPontuação 0/0
  • “Fazer checkout do PR #128 localmente para testá-lo”

  • “Toda segunda-feira, exportar todas as issues abertas de 40 repositórios para uma planilha”

  • “Postar no chat da equipe no instante em que uma release é publicada”

  • “Ver pelo terminal se as verificações do seu PR passaram”

  • “Buscar 50 PRs com as revisões e labels deles numa única requisição”

  • “Rotular toda issue nova que mencione “crash””

Principais conclusões

  • O gh cuida de pull requests, issues, execuções, releases e chamadas diretas à API pelo terminal.

  • A API REST devolve JSON por recurso; autentique-se com um token no cabeçalho Authorization.

  • Siga o cabeçalho Link para a paginação e fique de olho nos cabeçalhos de limite de requisições.

  • O GraphQL busca dados aninhados numa única requisição; webhooks e o Actions reagem a eventos em vez de ficar consultando.

Quiz da aula

7 perguntas · aprovação com 5 acertos · até 50 XP

Ao passar, você conclui a aula e mantém sua sequência. As perguntas erradas voltarão em sessões de revisão.

Pratique: automatize tarefas do GitHub com Python

O trabalho real no GitHub envolve muita automação pequena: conferir CODEOWNERS, expandir matrizes de build, atualizar versões, ler a API. Escreva esses utilitários em Python e execute-os com entradas de exemplo, localmente no navegador e sem precisar de conta no GitHub.

Exercício 1

Siga as páginas

+25 XP

Simule uma API paginada. A entrada é uma série de páginas, cada uma com uma linha de cabeçalho Link: seguida, na linha seguinte, de um array JSON de issues. A partir da primeira página, siga os links rel="next", associando o page=N de cada URL à N-ésima página da entrada (as páginas são numeradas a partir de 1) até não haver link next. Junte os numbers das issues.

Imprima fetched N pages, M issues e depois os números das issues abertas ("state": "open") em ordem, como open: 3 7 12. Uma página cujo cabeçalho Link está vazio não tem próxima página.

  • Três páginas
  • Uma página
main.py
Carregando editor…

O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.

Exercício 2

Fique abaixo do limite de requisições

+25 XP

O seu script precisa fazer várias chamadas à API. A entrada é calls_needed remaining limit reset_in_minutes - quantas chamadas você precisa, quantas ainda restam na janela atual, o limite por hora e quando a janela é reiniciada. Imprima now: N calls e depois quantas chamadas vão em cada janela de uma hora seguinte (after 25 min: 5000 calls, depois after 85 min: ..., somando 60 minutos a cada vez) até todas terminarem, e depois total wait: X min (o início da última janela usada, ou 0 se tudo couber agora).

  • Exportação grande
  • Cabe agora
main.py
Carregando editor…

O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.

Dúvidas sobre esta lição

Travou em algum ponto? Pergunte. Descobriu algo? Compartilhe. Explicar também é uma ótima forma de aprender.

Carregando publicações…