Como usar o GitHub CLI (gh) para automatizar tarefas do repositório

1. Introdução ao GitHub CLI (gh) e instalação

O GitHub CLI (gh) é uma ferramenta oficial de linha de comando que permite interagir com o GitHub diretamente do terminal, eliminando a necessidade de alternar constantemente entre navegador e console. Para automatizar tarefas do repositório, o gh oferece uma interface programática completa, ideal para scripts e pipelines de CI/CD.

A instalação é simples. No Ubuntu/Debian:

sudo apt install gh

No macOS via Homebrew:

brew install gh

Após instalar, a autenticação é o primeiro passo:

gh auth login

Esse comando guia você pelo processo de login interativo, gerando um token de autenticação. Para verificar a instalação e obter ajuda:

gh --version
gh help

Comandos de configuração úteis:

gh config set editor vim
gh config set git_protocol ssh

2. Gerenciamento de issues e pull requests

Criar issues programaticamente é uma das automações mais comuns. Para criar uma nova issue:

gh issue create --title "Corrigir bug no login" --body "Descrição detalhada do problema" --label bug

Listar issues abertas atribuídas a você:

gh issue list --assignee @me --state open

Para automatizar pull requests com templates:

gh pr create --base main --head feature-branch --title "Nova funcionalidade" --body "$(cat .github/PULL_REQUEST_TEMPLATE.md)" --label enhancement

Revisar e mesclar PRs via linha de comando:

gh pr review 42 --approve --body "Código aprovado, parabéns!"
gh pr merge 42 --merge --delete-branch

Esses comandos são especialmente úteis em scripts que processam múltiplos PRs em lote, economizando horas de trabalho manual.

3. Automação de workflows e CI/CD

O GitHub CLI permite disparar e monitorar GitHub Actions diretamente do terminal. Para executar um workflow manualmente:

gh workflow run deploy.yml --ref main --field environment=production

Acompanhar a execução em tempo real:

gh run watch

Visualizar logs de uma execução específica:

gh run view 1234567890 --log

Listar execuções recentes:

gh run list --limit 10 --workflow=ci.yml

Cancelar uma execução que está travada:

gh run cancel 1234567890

Reiniciar uma execução falha:

gh run rerun 1234567890

Essa automação é essencial para pipelines que precisam reagir a falhas ou executar deploys sob demanda sem intervenção manual.

4. Manipulação de repositórios e branches

Clonar repositórios e criar forks é simplificado:

gh repo clone owner/repo
gh repo fork owner/repo --clone=true

Para criar branches remotas programaticamente, usamos a API:

gh api repos/:owner/:repo/git/refs --method POST \
  --field ref="refs/heads/feature-x" \
  --field sha="$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha')"

Deletar uma branch remota:

gh api repos/:owner/:repo/git/refs/heads/feature-x --method DELETE

Sincronizar forks via script:

#!/bin/bash
gh repo sync owner/forked-repo --branch main
git fetch upstream
git merge upstream/main
git push origin main

Esses comandos permitem gerenciar dezenas de branches e forks em segundos, algo impraticável manualmente.

5. Automação de releases e tags

Criar releases com assets é direto:

gh release create v1.0.0 --title "Versão 1.0.0" --notes "Notas de release" ./dist/app.zip

Listar releases existentes:

gh release list --limit 5

Deletar uma release problemática:

gh release delete v0.9.0 --yes

Gerar changelogs automáticos:

gh release generate-notes --tag v1.1.0 --previous-tag v1.0.0

Esse recurso é valioso para equipes que precisam manter changelogs atualizados sem esforço manual, integrando-o a workflows de CI/CD.

6. Gerenciamento de permissões e equipes

Adicionar colaboradores via API:

gh api repos/:owner/:repo/collaborators/username --method PUT --field permission=push

Remover colaboradores:

gh api repos/:owner/:repo/collaborators/username --method DELETE

Gerenciar equipes e permissões:

gh api orgs/:org/teams/:team/repos/:owner/:repo --method PUT --field permission=admin

Auditar permissões de todos os colaboradores:

gh api repos/:owner/:repo/collaborators --jq '.[] | "\(.login): \(.role_name)"'

Esses scripts são fundamentais para organizações que precisam aplicar políticas de acesso consistentes em dezenas de repositórios.

7. Scripts avançados e boas práticas de automação

Combinar comandos gh com loops e condicionais em shell script:

#!/bin/bash
# Script para fechar issues antigas sem atividade
for issue in $(gh issue list --state open --label stale --json number --jq '.[].number'); do
  echo "Fechando issue #$issue"
  gh issue close $issue --comment "Issue fechada automaticamente por inatividade"
done

Usar gh api para endpoints não cobertos:

# Buscar estatísticas de contribuição
gh api repos/:owner/:repo/stats/contributors --jq '.[] | "\(.author.login): \(.total) commits"'

Tratamento de erros e logs:

#!/bin/bash
set -e
trap 'echo "Erro na linha $LINENO"; exit 1' ERR

if ! gh pr create --base main --head feature; then
  echo "Falha ao criar PR" | tee -a error.log
  exit 1
fi

Segurança com tokens e secrets:

# Usar secrets do GitHub Actions
gh secret set DEPLOY_KEY --body "$(cat deploy_key.pem)"
gh secret list --json name,updated_at

Nunca hardcode tokens em scripts. Utilize variáveis de ambiente e secrets do GitHub Actions para manter a segurança.

Referências