Upload de imagens para o GitHub (gh-image)

O GitHub não tem uma API pública para upload de imagens — a interface web usa um endpoint interno que gera URLs user-attachments com escopo para a visibilidade do repositório. gh-image (MIT, © drogers0) replica esse fluxo como uma extensão gh da CLI, para que um agente possa fazer upload de uma imagem local do terminal e receber de volta uma linha de imagem Markdown pronta para incorporar.

Visão Geral

Esta habilidade utiliza gh-image para transformar um arquivo de imagem local em um URL user-attachments do GitHub hospedado, e então incorpora esse URL em um pull request, issue ou comentário. É a capacidade "anexar uma captura de tela" que faltava para agentes de terminal.

Quando Usar Esta Habilidade

Use esta habilidade quando for solicitado a:

• "Anexar uma captura de tela ao PR" ou "adicionar uma imagem à descrição do PR"
• "Colocar esta imagem na issue" / "comentar com estas capturas de tela"
• "Mostrar os resultados do teste / antes e depois no PR"
• Incorporar qualquer imagem local no Markdown do GitHub sem sair do terminal

Como Funciona

Passo 1: Verificar pré-requisitos

gh auth status                                   # gh installed & authenticated
gh extension list | grep -q 'drogers0/gh-image' \
  || gh extension install drogers0/gh-image      # review/pin the extension source first

gh-image não usa o token gh para o upload (esse endpoint rejeita tokens). Ele precisa de um cookie user_session do GitHub, resolvido nesta ordem: flag --token <value> → variável de ambiente GH_SESSION_TOKEN (use em CI/headless) → o armazenamento de cookies de um navegador logado (padrão para uso local).

Passo 2: Upload

# Use an absolute path; --repo is optional inside a repo working dir.
gh image "/abs/path/screenshot.png" --repo <owner>/<repo>

gh image imprime Markdown para stdout, uma linha por imagem:

![screenshot.png](https://github.com/user-attachments/assets/<uuid>)

Capture essa saída — é a referência que pode ser incorporada.

Passo 3: Incorporar no PR / issue / comentário

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
BODY="$(gh pr view <pr> --repo owner/repo --json body -q .body)"
printf '%s\n\n## Screenshots\n\n%s\n' "$BODY" "$MD" \
  | gh pr edit <pr> --repo owner/repo --body-file -

Use gh pr comment, gh issue edit ou gh issue comment com --body-file - para outros destinos. Sempre passe --body-file - (não --body inline) para que corpos de múltiplas linhas e caracteres especiais não quebrem o quoting do shell.

Passo 4: Verificar

gh pr view <pr> --repo owner/repo --json body -q .body   # confirm URL present

Exemplos

• Anexar uma captura de tela do CleanShot ao PR #42: faça upload do arquivo, anexe-o sob um título ## Screenshots no corpo do PR.
• Incorporar imagens de antes/depois em um README: faça upload de ambas, cole as duas linhas de Markdown no README na seção relevante.

Melhores Práticas

• Resolva globs para caminhos absolutos primeiro; coloque caminhos com espaços/Unicode entre aspas.
• Para dimensionamento de exibição, incorpore uma tag HTML em vez de Markdown puro: <img width="800" src="https://github.com/user-attachments/assets/<uuid>" />.
• Em CI, defina GH_SESSION_TOKEN a partir de uma conta de bot dedicada.

Limitações

• Cookie de sessão necessário. Um cookie user_session concede acesso total à conta (não com escopo como um PAT) — trate-o como uma senha; use uma conta de bot em CI.
• É necessário ter acesso de escrita ao repositório de destino; organizações que impõem SAML SSO precisam que a sessão seja autorizada em https://github.com/orgs/<org>/sso primeiro.
• Imagens de repositórios privados permanecem privadas: o URL user-attachments herda a visibilidade do repositório, portanto, uma busca anônima em um repositório privado retorna 404/403 por design.
• Windows + Chrome 127+ não consegue ler cookies (limitação da biblioteca) — use outro navegador ou GH_SESSION_TOKEN.
• A habilidade incorpora o próprio Markdown; gh-image apenas imprime o URL.