Publicar

Você já fez o push final

Neste ponto, você executou as phases, 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
- astro.config.mjs, se existir
- vite.config.js, vite.config.ts ou configuração equivalente, se existir
- README.md
- PLAN.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
  - Astro GitHub Pages: https://docs.astro.build/en/guides/deploy/github/
  - Vite static deploy: https://vite.dev/guide/static-deploy

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, imagens ou rotas corretas, normalmente o problema está no base, no public path ou em caminhos absolutos. As docs de Astro e Vite explicam esse ajuste para GitHub Pages.

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.

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. Pesquise um artista.
3. Abra a discografia.
4. Abra os detalhes de um álbum.
5. Teste no celular ou em largura pequena.
6. Atualize a página e confirme que ela continua carregando.
7. Abra o console do navegador e confira se 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.

O próximo capítulo existe para isso: Onde isso quebra. Use ele quando tiver um erro específico, um log ou um comportamento claro para investigar.

O fluxo completo agora fecha: preparar contexto, planejar, construir em phases, 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