github-cli

name	github-cli
description	Opera o GitHub pela linha de comando com `gh`. Use quando o usuário quiser criar/clonar/configurar repositório, abrir ou editar issues e PRs, comentar, gerenciar labels, pedir revisores, revisar PR, buscar issues/PRs/repos, ou ligar issues entre si (sub-issue, bloqueio) e PR a issue; ou quando outra skill precisar da sintaxe do `gh`.

GitHub pela CLI

Toda chamada gh roda headless: sem TTY, sem prompt, sem editor. Um comando que abriria prompt trava a sessão — passe título, corpo e destino por flag (--title, --body-file -, -R), nunca --web nem -e/--editor.

Todo comando aceita o alvo -R owner/repo. Dentro de um clone o alvo é implícito; fora dele, ou com múltiplos remotes, declare -R explicitamente (ou fixe uma vez com gh repo set-default owner/repo).

Antes de qualquer escrita, confirme o contexto: gh auth status (conta e escopos) e gh repo view --json nameWithOwner,defaultBranchRef.

Repositório

gh repo create owner/nome --private --clone                 # cria e clona
gh repo create nome --public --source=. --push              # publica um repo local existente
gh repo create nome --private --template owner/modelo       # a partir de template
gh repo clone owner/repo [dir] -- --depth=1                 # flags após `--` vão para o git
gh repo fork owner/repo --clone
gh repo view owner/repo --json name,description,visibility,defaultBranchRef
gh repo list owner --limit 50 --json name,visibility,updatedAt
gh repo set-default owner/repo                              # fixa o alvo deste diretório
gh repo sync                                                # atualiza o fork a partir do upstream

Configuração (gh repo edit): --description, --homepage, --add-topic/--remove-topic, --default-branch, --visibility {public|private|internal} --accept-visibility-change-consequences, --enable-issues/--enable-wiki/--enable-projects/--enable-discussions, --enable-squash-merge/--enable-merge-commit/--enable-rebase-merge, --delete-branch-on-merge, --enable-auto-merge, --allow-update-branch, --squash-merge-commit-message {default|pr-title|pr-title-commits|pr-title-description}.

Issues

gh issue create --title "Corpo do bug" --body-file - <<'EOF'
Descrição em markdown.
EOF
gh issue create -t "Título" -b "Corpo" -l bug -l "help wanted" -a @me -m "v1.0" --type Bug
gh issue list --state open --label bug --assignee @me --limit 50
gh issue view 123 --comments
gh issue edit 123 --title "..." --body-file corpo.md
gh issue close 123 --reason "not planned" --comment "fora de escopo"
gh issue close 123 --reason duplicate --duplicate-of 99
gh issue reopen 123
gh issue develop 123 --checkout                             # cria branch já vinculada à issue
gh issue transfer 123 owner/outro-repo
gh issue pin 123 / gh issue lock 123 / gh issue delete 123 --yes

--body-file - lê de stdin: é o caminho confiável para corpos multi-linha com markdown, crases e acentos.

Assinatura em lote: gh issue edit 23 34 45 --add-label triage aceita vários números.

Pull requests

git push -u origin minha-branch
gh pr create --base main --title "..." --body-file - --reviewer monalisa --reviewer minhaorg/time --label feature --draft
gh pr create --fill                                         # título e corpo a partir dos commits
gh pr list --state open --base main --label bug --json number,title,reviewDecision
gh pr view 42 --json title,state,reviewDecision,statusCheckRollup,closingIssuesReferences
gh pr diff 42 / gh pr checkout 42 / gh pr checks 42 --watch --fail-fast
gh pr edit 42 --add-reviewer fulano --remove-reviewer cicrano --add-label ready --base develop
gh pr ready 42                                              # sai de draft
gh pr update-branch 42
gh pr merge 42 --squash --delete-branch [--auto]
gh pr revert 42

--auto no merge agenda a fusão para quando checks e aprovações passarem — o modo seguro quando o CI ainda está rodando.

Revisão

gh pr review 42 --approve -b "LGTM"
gh pr review 42 --request-changes -b "faltam testes"
gh pr review 42 --comment -b "observação sem veredito"
gh pr comment 42 --body "..."                               # comentário solto na conversa
gh pr comment 42 --edit-last --body "..."                   # edita o próprio último comentário
gh issue comment 123 --edit-last --create-if-none --body "..."
gh issue comment 123 --delete-last --yes

gh pr review posta um veredito sobre o PR inteiro. Para comentário ancorado em linha de arquivo, use a API — veja references/review-linha-a-linha.md.

Revisores: --reviewer/--add-reviewer aceita login de pessoa, org/time e @copilot. Re-pedir revisão de quem já revisou é o mesmo --add-reviewer com o mesmo login.

Labels

gh label list --search perf --sort name --limit 100
gh label create bug --color E99695 --description "Algo quebrado" --force
gh label edit bug --name defeito --color D93F0B
gh label delete obsoleta --yes
gh label clone owner/repo-modelo                            # copia o conjunto de labels de outro repo
gh issue edit 123 --add-label bug --remove-label triage
gh pr edit 42 --add-label ready --remove-label wip

Cor é hex de 6 dígitos sem #. --force no create atualiza a label se já existir — o jeito idempotente de semear labels.

Vínculos entre issues e PRs

PR resolve issue: escreva Closes #123 (ou Fixes/Resolves) no corpo do PR. É o único vínculo que fecha a issue no merge.

gh pr create --title "..." --body "Closes #123"
gh pr edit 42 --body-file - <<'EOF'
Descrição.

Closes #123
Closes #124
EOF
gh pr view 42 --json closingIssuesReferences                 # confirma o vínculo

Para issue em outro repo: Closes owner/repo#123.

Sub-issues (hierarquia pai/filho):

gh issue create --title "Etapa 1" --parent 100
gh issue edit 100 --add-sub-issue 123,124
gh issue edit 100 --remove-sub-issue 124
gh issue edit 123 --parent 100 / --remove-parent
gh issue view 100 --json subIssues,subIssuesSummary

Dependências bloqueantes:

gh issue create --title "Deploy" --blocked-by 200,201 --blocking 300
gh issue edit 123 --add-blocked-by 200 --add-blocking 300,301
gh issue edit 123 --remove-blocked-by 200
gh issue view 123 --json blockedBy,blocking

Todos aceitam número ou URL completa da issue. Relações entre repos diferentes exigem a URL.

Busca

gh issue list --search/gh pr list --search buscam dentro do alvo; gh search issues|prs|repos|code|commits busca o GitHub inteiro.

gh search issues --owner minhaorg --label bug --state open --sort updated
gh search prs --review-requested @me --state open
gh issue list --search "error no:assignee sort:created-asc"

Qualificadores, negação (-label:bug), datas e --json/--jq estão em references/busca-e-json.md.

Escapes

gh api alcança qualquer endpoint REST ou GraphQL que os subcomandos não cobrem: gh api repos/{owner}/{repo}/issues/123/sub_issues, gh api --paginate, gh api graphql -f query='...'. Detalhes em references/busca-e-json.md.

Escopos de token faltando causam 403: gh auth refresh -s project (Projects), -s workflow (Actions), -s admin:org. Confira o que já tem com gh auth status.