Publicar

Você já fez o push final

Neste ponto, você executou as fases, validou localmente, gerou reports, fez o commit final e enviou o código para o GitHub. Agora falta uma coisa: publicar o projeto.

A referência principal aqui é a documentação oficial do GitHub sobre configurar a fonte de publicação do Pages.

O que o GitHub Pages precisa

GitHub Pages publica arquivos estáticos: HTML, CSS, JavaScript e assets prontos para o navegador. Ele pode publicar a partir de uma branch, usando a raiz da branch ou a pasta /docs.

Em projetos com build, a pasta gerada costuma ser dist, mas o GitHub Pages não permite simplesmente escolher dist dentro da branch principal. Por isso, o caminho mais simples para o primeiro deploy é colocar o conteúdo gerado na raiz de uma branch separada chamada gh-pages.

Sim, isso cria duas versões do projeto no repositório. Neste capítulo, isso é uma escolha consciente: primeiro queremos uma URL pública funcionando. Automatizar esse processo pode vir depois.

1. Preparar a branch de deploy

Agora peça ao seu agente de código para preparar o deploy. Ele precisa olhar o projeto real, descobrir o comando de build, confirmar a pasta de saída e verificar se existe configuração de base ou public path para URLs do GitHub Pages.

Você vai me ajudar a publicar este projeto no GitHub Pages pela primeira vez usando uma branch de deploy.

Antes de alterar qualquer arquivo, leia:
- package.json se existir
- index.html
- qualquer arquivo de build config (vite.config.js, webpack.config.js, etc.) se existir
- DEV_PLAN.md
- ROADMAP.md
- AGENTS.md ou CLAUDE.md

CONTEXTO
- Eu já terminei o projeto, fiz o commit final e fiz push para o GitHub.
- Agora quero o caminho com menor atrito para ver o projeto em uma URL pública.
- O GitHub Pages deve publicar a partir de uma branch de deploy.
- A branch principal continua com o código-fonte.
- A branch gh-pages deve conter apenas o site estático gerado, na raiz da branch.
- Use a documentação oficial atual como referência:
  - GitHub Pages publishing source: https://docs.github.com/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site

TAREFA
Prepare o primeiro deploy do projeto no GitHub Pages usando a branch gh-pages.

Faça o seguinte:
1. Confirme qual comando de build existe no package.json.
2. Confirme qual é a pasta de saída do build. Normalmente é dist, mas verifique a configuração real do projeto.
3. Verifique se a configuração do framework precisa de base, public path ou site para funcionar em:
   https://[USUARIO_GITHUB].github.io/[NOME_DO_REPO]/
4. Rode ou me oriente a rodar o build de produção.
5. Prepare um procedimento seguro para publicar o conteúdo gerado na raiz da branch gh-pages.
6. Explique exatamente quais configurações devo escolher em Settings > Pages:
   - Source: Deploy from a branch
   - Branch: gh-pages
   - Folder: / (root)
7. Explique como validar a URL pública depois.

REGRAS IMPORTANTES
- Não publique segredos.
- Não mude a stack do projeto.
- Não use GitHub Actions agora; isso fica como upgrade posterior.
- Não use comandos destrutivos sem explicar antes.
- Não reescreva uma branch de deploy existente sem pedir confirmação.
- Se a pasta de build não for dist, adapte o procedimento à configuração real.
- Antes de executar qualquer comando que altere branches, me mostre o plano.

O ponto importante: não aceite um comando só porque parece familiar. O agente precisa confirmar a pasta gerada pelo build e explicar como ela vai parar na raiz da branch gh-pages.

2. Conferir URL, base e caminhos

Para repositórios comuns, o GitHub Pages publica no formato: https://[USUARIO_GITHUB].github.io/[NOME_DO_REPO]/.

Essa parte é onde muitos primeiros deploys quebram. Se o site abrir sem CSS ou com caminhos incorretos, investigue se algum asset usa caminho absoluto que aponta para / em vez de um caminho relativo. A documentação do GitHub Pages explica como configurar a fonte de publicação corretamente.

3. Configurar o GitHub Pages

Depois que a branch gh-pages existir no GitHub com os arquivos gerados na raiz, configure o Pages pela interface do GitHub:

1. Abra o repositório no GitHub.
2. Entre em Settings → Pages.
3. Em Build and deployment, escolha Deploy from a branch.
4. Em branch, selecione gh-pages.
5. Em folder, selecione / (root).
6. Clique em Save.

4. Abrir a URL pública

O GitHub pode levar alguns minutos para publicar. A própria página de Settings → Pages costuma mostrar a URL quando o site fica disponível.

A URL normalmente será: https://[USUARIO_GITHUB].github.io/[NOME_DO_REPO]/. Se ela ainda der 404 logo depois de salvar, espere alguns minutos antes de mexer em tudo.

Checklist de produção antes de publicar

Antes de abrir o site para outras pessoas, passe por este checklist mínimo. Ele não transforma o projeto em enterprise, mas evita erros comuns de publicação:

• Nenhum secret, token ou chave de API no client ou no repositório.
• Permissões e escopo mínimos: o site só faz o que a v1 promete.
• CORS e chamadas de API funcionando na URL pública, não só no localhost.
• Estados de erro visíveis: loading, vazio e falha de rede.
• Console do navegador sem erro crítico no fluxo principal.
• Plano simples de rollback: você sabe voltar para o commit ou deploy anterior.
• Dependências revisadas: nada suspeito ou desnecessário para um site estático.
• Validação manual do caminho crítico: página carrega, stories aparecem, links externos abrem.

5. Validar como usuário

Agora valide o projeto publicado como alguém que abriu o link pela primeira vez:

1. Abra a página inicial publicada.
2. As top stories do Hacker News aparecem no layout de jornal.
3. Clique em um link de story e confirme que abre a URL correta.
4. Teste no celular ou em largura pequena.
5. Atualize a página e confirme que ela continua carregando.
6. Abra o console do navegador e confirme que não há erro óbvio.

Quando algo quebra

Se a URL dá 404, confira se a branch gh-pages existe no GitHub, se o Pages está usando Deploy from a branch, se a pasta é / (root) e se você esperou alguns minutos.

Se a página abre sem estilo, imagens ou rotas corretas, investigue base, public path e caminhos absolutos. Se o site abre mas os dados não carregam, investigue API, CORS e console do navegador.

Se os dados não carregam, verifique o console. A HackerNews Firebase API é pública e não tem restrição de CORS, então o problema provavelmente é de rede, URL incorreta ou erro no script de fetch.

O fluxo completo agora fecha: preparar contexto, planejar, construir em fases, validar localmente, fazer push e publicar. O primeiro deploy não precisa ser perfeito como infraestrutura; ele precisa funcionar, ser compreendido e abrir caminho para automação quando ela fizer sentido.

git add .
git commit -m "[resuma o que foi feito neste capitulo]"
git push