Workflow mínimo
Publicar HTML no GitHub Pages pode ser só um push — ou um workflow estável com validação.
name: deploy
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v4
- name: validate
run: python3 scripts/validate-site.py
- uses: actions/upload-pages-artifact@v3
with:
path: .
- id: deployment
uses: actions/deploy-pages@v4
Dicas
- Rode o validador local antes do push
- Use
concurrency para cancelar deploys antigos
- Secrets só quando precisar de token externo
Combina bem com o curso de Docker quando o próximo passo for containerizar o front.
O workflow explicado, linha a linha
| Trecho | O que faz |
|---|
name: deploy | Nome do workflow na aba Actions. |
on: push: branches: [main] | Dispara a cada push na branch main. |
permissions: contents: read | O job só pode ler o código do repositório. |
pages: write e id-token: write | Permissões necessárias para o job publicar no GitHub Pages. |
runs-on: ubuntu-latest | Executa em uma máquina virtual Linux da própria GitHub. |
environment: name: github-pages | Declara o ambiente de publicação, exigido pelo deploy-pages. |
uses: actions/checkout@v4 | Baixa o código do repositório para a máquina do job. |
run: python3 scripts/validate-site.py | Roda o validador. Se falhar, o deploy não acontece. |
actions/upload-pages-artifact@v3 com path: . | Empacota a pasta atual como o artefato do site. |
actions/deploy-pages@v4 | Publica o artefato no GitHub Pages. |
| Gatilho | Quando dispara |
|---|
push | a cada envio para as branches listadas |
pull_request | ao abrir ou atualizar um PR, bom para rodar só a validação |
workflow_dispatch | manualmente, pelo botão na aba Actions |
O ambiente github-pages e a URL publicada
| Trecho | O que faz |
|---|
environment: name: github-pages | Liga o job ao ambiente de publicação do GitHub Pages. Sem ele o deploy-pages costuma falhar com "Missing environment". |
url: ${{ steps.deployment.outputs.page_url }} | Mostra o endereço do site publicado no resumo da execução. |
id: deployment | Dá um nome ao passo de deploy, para outro trecho ler a saída dele (steps.deployment.outputs.page_url). |
Nas configurações do repositório, em Pages, a origem precisa estar como GitHub Actions.
Erros comuns
| Sintoma | Causa provável | Solução |
|---|
| Erro "Missing environment" | O job de deploy não declara o environment. | Acrescente environment: name: github-pages, como no exemplo acima. |
| O deploy falha por permissão | Faltam pages: write ou id-token: write. | Confira o bloco permissions do workflow. |
| O site não atualiza depois do push | A origem do Pages não está em GitHub Actions ou o validador falhou. | Veja a aba Actions e as configurações de Pages. |
| O workflow nem aparece | O arquivo não está em .github/workflows/ ou o YAML tem erro de indentação. | Mova o arquivo e valide o YAML. |