CI e publicação
Como um robô confere cada mudança antes de ela seguir: workflows do GitHub Actions, leitura de falhas, segredos e publicação de um site.
Cerca de 15 min · Revisado em
Ao final, você vai conseguir
- Explicar o que a CI faz e por que ela roda em cada pull request
- Ler e completar um workflow do GitHub Actions com
on,jobs,runs-on,useserun - Encontrar o erro no log de uma CI que falhou e reproduzi-lo localmente
- Separar o que vai no repositório do que deve ser um segredo
- Descrever como um site estático é publicado a partir do build
Imagine mandar um pull request e, em dois minutos, um robô avisar: “o teste do frete quebrou na linha 12”. Ninguém precisou lembrar de rodar nada, e o erro não chegou a quem usa o site. Em quase toda vaga de tecnologia, esse robô existe e se chama CI. Saber ler o que ele diz, e configurar o seu, é o que faz um projeto de portfólio parecer trabalho de verdade.
Uma conferência antes de entregar
CI vem de *Continuous Integration*, integração contínua. É a prática de juntar mudanças ao código principal com frequência, e a cada mudança um serviço roda automaticamente as verificações do projeto: lint, checagem de tipos, testes e build.
Você viu na aula de Git que mudanças chegam ao main por um pull request (PR). É nele que a CI aparece: cada verificação vira um status check, um selo verde, vermelho ou amarelo (rodando) ao lado do PR.
- Lint
- Uma ferramenta que lê o código procurando erros comuns e problemas de estilo, sem executar nada. Exemplo: ESLint em JavaScript, Ruff em Python.
- Build
- A etapa que transforma o código-fonte no que vai ser publicado, como a pasta
dist/de um site feito com Vite. - Runner
- O computador temporário que executa a CI. Ele nasce vazio, roda os passos e é apagado no fim.
Seu colega diz: “Não preciso de CI, eu sempre rodo os testes antes de subir”. Qual é o melhor argumento a favor da CI?
- A CI roda as mesmas verificações em um computador limpo, para toda mudança de qualquer pessoa
- A CI deixa o código mais rápido
- A CI corrige os erros sozinha
- A CI substitui a revisão de código por outra pessoa
O arquivo que manda na CI
No GitHub Actions, a CI do próprio GitHub, a conferência é descrita em um arquivo YAML dentro de .github/workflows/. YAML é um formato de texto em que a indentação (os espaços no começo da linha) mostra o que está dentro do quê.
Um workflow de CI para um projeto Node. Explore cada parte.
name: CI
on:
pull_request:
push:
branches: [main]
jobs:
verificar:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run lint
- run: npm test
- run: npm run build- name: O nome que aparece na aba Actions e no status check do PR. Escolha algo curto.
- on: Os gatilhos: quando o workflow roda. Aqui, em todo pull request e em todo push para o
main. Semon, o arquivo não faz nada. - jobs: Um workflow tem um ou mais jobs (trabalhos). Cada job roda em um runner próprio e, por padrão, em paralelo com os outros.
verificaré o nome que você escolheu. - runs-on: Em que tipo de máquina o job roda.
ubuntu-latesté um Linux novo a cada execução: nada do que você instalou na última vez continua lá. - uses:
useschama uma action: um passo pronto, escrito por outra pessoa.checkoutbaixa o código do repositório para o runner. Sem ele, a máquina está vazia. O@v4fixa a versão. - with:
withpassa opções para a action. Aqui: instale o Node 22 e guarde em cache as dependências do npm entre execuções. - run:
runexecuta um comando no terminal do runner, igual você faria no seu. Os passos rodam em ordem; se um falha, os seguintes não rodam e o job fica vermelho.
Complete o workflow: ele deve rodar em pull requests, numa máquina Ubuntu, baixar o código e instalar as dependências travadas.
name: CI
on: ____
jobs:
testes:
runs-on: ____
steps:
- uses: actions/____@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- ____: npm ____
- run: npm testQuando fica vermelho
Um X vermelho no PR não é bronca: é informação. O caminho é sempre o mesmo: abrir o job que falhou, achar o primeiro erro no log e reproduzir no seu computador.
O trecho do log de uma CI que falhou. Onde está a pista?
Run npm test
> loja@1.0.0 test
> vitest run
✓ src/carrinho.test.ts (4 tests) 12ms
❯ src/frete.test.ts (3 tests | 1 failed) 18ms
× calcula frete grátis acima de R$ 150
→ expected 15 to be 0
Test Files 1 failed | 1 passed (2)
Tests 1 failed | 6 passed (7)
Error: Process completed with exit code 1.- Passo que falhou: O log é dividido por passo. Os anteriores (checkout,
npm ci, lint) passaram. O problema está aqui, não na instalação. - O que passou: Ajuda a delimitar: o carrinho está bem. Você não precisa olhar esse arquivo.
- O teste que quebrou: Arquivo e nome do teste. Um bom nome de teste já diz qual regra de negócio foi violada.
- Esperado e recebido: O coração da pista: o teste esperava frete
0e o código devolveu15. A regra do frete grátis não está sendo aplicada. - Código de saída: Todo comando termina com um número.
0significa sucesso; qualquer outro, falha. É esse número que a CI usa para decidir verde ou vermelho.
Do X vermelho ao verde
Seu PR na loja falhou. Investigue pelo terminal com a CLI do GitHub (gh), reproduza, corrija e envie de novo.
Veja o estado das verificações do seu pull request.
gh pr checksSome checks were not successful 1 failing, 1 successful, 0 pending checks X CI/verificar (pull_request) 41s ✓ Netlify/deploy-preview 28sLeia só o pedaço do log que falhou, sem rolar milhares de linhas.
gh run view --log-failedverificar Run npm test ❯ src/frete.test.ts (3 tests | 1 failed) verificar Run npm test × calcula frete grátis acima de R$ 150 verificar Run npm test → expected 15 to be 0 verificar Run npm test Error: Process completed with exit code 1.Reproduza a falha no seu computador rodando os testes.
npm test❯ src/frete.test.ts (3 tests | 1 failed) × calcula frete grátis acima de R$ 150 → expected 15 to be 0 Tests 1 failed | 6 passed (7)Você trocou
>por>=na regra do frete emsrc/frete.ts. Rode os testes de novo para confirmar.npm test✓ src/carrinho.test.ts (4 tests) ✓ src/frete.test.ts (3 tests) Tests 7 passed (7)Faça o commit da correção com a mensagem
corrige frete gratis.git commit -am "corrige frete gratis"[corrige-frete 4e1c9a2] corrige frete gratis 1 file changed, 1 insertion(+), 1 deletion(-)Envie o commit para o GitHub.
git pushTo github.com:ana/loja.git b71d03f..4e1c9a2 corrige-frete -> corrige-freteConfira as verificações do PR mais uma vez.
gh pr checksAll checks were successful 0 failing, 2 successful, 0 pending checks ✓ CI/verificar (pull_request) 38s ✓ Netlify/deploy-preview 26s
Um teste de interface falha na CI, você clica em “Re-run jobs” e ele passa, sem nenhuma mudança no código. O que isso indica?
- Que o teste é instável (flaky) e precisa ser investigado
- Que estava tudo certo e a CI errou
- Que é melhor configurar a CI para repetir todo teste três vezes
O log mostra 300 linhas de erro. Por que procurar o primeiro erro, e não o último?
Porque um erro costuma causar vários outros em cascata. Se a instalação de uma dependência falhou, tudo que vem depois reclama dela. Corrigir a primeira causa muitas vezes faz o resto sumir.
Mais rápido e sem vazar senha
Como o runner nasce vazio, toda execução baixaria as dependências do zero. O cache guarda essa pasta entre execuções, usando o arquivo de lock como chave: se o package-lock.json não mudou, o download é reaproveitado.
Outra necessidade: às vezes a CI precisa de uma senha, como o token para publicar o site. Isso nunca vai no código. Vai em secrets, uma área do repositório onde o valor fica guardado criptografado e é escondido nos logs.
Lendo um segredo dentro do workflow
- run: npm run deploy
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}Para cada item, onde ele deve ficar?
Pode ir no repositório · Deve ser um segredo
- O arquivo
.github/workflows/ci.yml - O token de deploy da Netlify
- Um
.env.examplecom nomes de variáveis e valores falsos - A senha do banco de produção
- O
package-lock.json - A chave de acesso da conta de nuvem
Do repositório para o mundo
Um site estático (HTML, CSS, JS, sem servidor próprio) é publicado copiando a pasta do build para um serviço de hospedagem. GitHub Pages, Netlify e Vercel fazem isso de graça para projetos pessoais, com HTTPS incluído.
O caminho de um push até o site no ar
- Você → GitHub: git push. Você envia o commit. Para o GitHub, isso é um evento que pode disparar workflows.
- GitHub → CI: Dispara o workflow. O gatilho
on: pushacorda um runner, que baixa o código. - CI → CI: lint, testes, build. A conferência. Se algo falha aqui, o fluxo para e o site antigo continua no ar, intacto.
- CI → Hospedagem: Envia a pasta dist/. Com tudo verde, só o resultado do build é publicado, não o código-fonte inteiro.
- Hospedagem → Você: Site no ar com HTTPS. A hospedagem troca a versão antiga pela nova e guarda o histórico de publicações.
Netlify e Vercel também criam um deploy de preview para cada PR: um endereço temporário com a versão nova, para revisar antes do merge. E como guardam cada publicação, voltar atrás (rollback) é escolher a anterior e republicá-la.
Coloque em ordem o que acontece desde a sua mudança até o site atualizado.
- Você abre um pull request com a mudança
- A CI roda lint, testes e build e o status fica verde
- Alguém revisa o PR e aprova
- O PR é integrado ao
main - O workflow do
mainpublica a pasta do build - A nova versão aparece no endereço do site
Seu site no GitHub Pages abre em branco, e o console mostra 404 para /assets/index.js. O endereço é ana.github.io/loja/. Qual é a causa mais provável?
- O build procura os arquivos na raiz do domínio, mas o site está na subpasta
/loja/ - O GitHub Pages não suporta JavaScript
- A CI não rodou os testes
Fechamento
- CI roda automaticamente as verificações do projeto (lint, tipos, testes, build) em um computador limpo a cada mudança.
- Um workflow do GitHub Actions diz quando rodar (
on), onde (runs-on) e o quê (stepscomuseserun). - Diante de uma falha, ache o primeiro erro no log, reproduza localmente, corrija e envie de novo; repetir um teste instável não é correção.
- Cache acelera a instalação; senhas e tokens ficam em secrets, nunca no repositório.
- Sites estáticos são publicados enviando a pasta do build para uma hospedagem, que guarda versões para rollback.
Coloque um projeto seu sob conferência automática
Escolha um projeto seu com pelo menos um teste. Você vai criar a CI, ver ela falhar de propósito e voltar ao verde. Pode pedir a uma IA uma proposta de workflow, mas confira se ela usa os scripts que existem de verdade no seu package.json (ou no seu projeto Python).
- Crie
.github/workflows/ci.ymlrodando instalação, lint, testes e build em cada pull request - Abra um PR com um teste quebrado de propósito e leia o log da falha até achar a linha do erro
- Corrija, envie de novo e veja o status ficar verde
- Publique o site (ou o relatório de testes) no GitHub Pages, Netlify ou Vercel
- Escreva no README como rodar o projeto localmente e como voltar para a versão anterior publicada