Upload e download de anexos de usuário do GitHub (gh-attach)

O GitHub não tem uma API pública para anexos de usuário. A interface web usa um endpoint interno que gera URLs github.com/user-attachments cuja visibilidade segue o repositório ao qual pertencem. gh-attach (MIT, sudosubin) replica esse fluxo de arrastar e soltar como uma extensão de linha de comando gh, para que um agente possa fazer upload de um arquivo local do terminal, obter uma URL de volta e, posteriormente, baixar um URL de anexo para um arquivo.

Visão Geral

Esta habilidade usa gh-attach para transformar um arquivo local (captura de tela, imagem, PDF, zip, log ou vídeo) em uma URL user-attachments hospedada no GitHub, e então incorpora essa URL em um pull request, issue ou comentário. Ela também baixa um URL de anexo existente de volta para um arquivo local. O GitHub renderiza automaticamente a URL como uma imagem, vídeo ou arquivo onde quer que seja colada, e a URL herda a visibilidade do repositório, então um upload de repositório privado permanece privado. Funciona tanto no GitHub Cloud quanto no GitHub Enterprise Server.

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"
• "Anexar este arquivo (PDF, zip, log, vídeo) à issue ou comentário"
• "Incorporar capturas de tela antes/depois" em um PR, issue ou README
• "Baixar este anexo do GitHub" de uma URL user-attachments

Como Funciona

Passo 1: Verificar pré-requisitos

gh auth status                                   # gh installed and authenticated
gh extension install sudosubin/gh-attach --pin v0.4.2 --force
gh extension list | grep -F 'sudosubin/gh-attach' # require the reviewed v0.4.2 release

Uploads usam um cookie de navegador do GitHub user_session, não o token gh (esse endpoint rejeita tokens). Por padrão, gh deve estar autenticado para que gh-attach possa selecionar a conta do navegador correspondente (família Chromium, família Firefox ou Safari). Se a conta errada for selecionada, adicione --browser <name> --profile <name>. Obtenha aprovação explícita antes de permitir que a extensão fixada acesse esse perfil de navegador interativo. Uploads em modo headless e CI são intencionalmente não suportados: nunca exporte, armazene ou passe um cookie user_session bruto para a extensão.

Passo 2: Upload

# Use an absolute quoted path; -R is optional inside a repo working dir.
URL=$(gh attach "/abs/path/screenshot.png" -R <owner>/<repo>)

gh attach imprime a URL em uma linha para stdout. Para GitHub Enterprise Server, use -R host/owner/repo. Capture a saída; ela é a referência incorporável.

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

printf '## Screenshots\n\n%s\n' "$URL" \
  | gh pr comment <pr> -R <owner>/<repo> --body-file -

Use gh pr edit, gh issue comment ou gh issue edit 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. O GitHub renderiza automaticamente a URL, então cole-a como está.

Passo 4: Download

# Specify the destination explicitly.
gh attach download "$URL" -O "/abs/path/out.png"

Downloads de anexos privados usam o token gh ativo, com cookies do navegador como fallback de autorização.

Exemplos

• Anexar uma captura de tela ao PR #42: faça o upload do arquivo, então anexe a URL sob um título ## Screenshots no corpo do PR com gh pr edit ... --body-file -.
• Incorporar capturas de tela antes/depois em um README: faça o upload de ambos os arquivos, cole as duas URLs no README na seção relevante.
• Baixar um anexo para revisão: execute gh attach download "$URL" -O out.zip para buscar um arquivo user-attachments localmente.

Melhores Práticas

• Resolva globs para caminhos absolutos primeiro e coloque entre aspas caminhos que contêm espaços ou Unicode.
• Para dimensionamento de exibição, incorpore uma tag HTML em vez da URL nua: <img width="800" src="$URL">.
• Mantenha os uploads interativos. Não coloque uma sessão de navegador do GitHub em CI, uma variável de ambiente, um armazenamento de segredos consumido por esta extensão ou um log de agente.
• gh-attach pode fazer upload de múltiplos arquivos simultaneamente e emitir saída Markdown ou JSON com filtragem estilo jq quando você precisar criar scripts em torno do resultado.

Limitações

• Cookie de sessão interativa necessário. Um cookie user_session concede acesso total à conta e não é escopado como um PAT. O caminho suportado é a extensão fixada e revisada lendo um perfil de navegador local explicitamente aprovado; injeção de cookie em CI e headless estão fora do escopo.

…