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, uses e run
  • 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. Sem on, 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: uses chama uma action: um passo pronto, escrito por outra pessoa. checkout baixa o código do repositório para o runner. Sem ele, a máquina está vazia. O @v4 fixa a versão.
  • with: with passa opções para a action. Aqui: instale o Node 22 e guarde em cache as dependências do npm entre execuções.
  • run: run executa 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 test

Quando 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 0 e o código devolveu 15. A regra do frete grátis não está sendo aplicada.
  • Código de saída: Todo comando termina com um número. 0 significa 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.

  1. Veja o estado das verificações do seu pull request.

    gh pr checks
    Some checks were not successful
    1 failing, 1 successful, 0 pending checks
    
    X  CI/verificar (pull_request)     41s
    ✓  Netlify/deploy-preview           28s
  2. Leia só o pedaço do log que falhou, sem rolar milhares de linhas.

    gh run view --log-failed
    verificar  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.
  3. 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)
  4. Você trocou > por >= na regra do frete em src/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)
  5. 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(-)
  6. Envie o commit para o GitHub.

    git push
    To github.com:ana/loja.git
       b71d03f..4e1c9a2  corrige-frete -> corrige-frete
  7. Confira as verificações do PR mais uma vez.

    gh pr checks
    All 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.example com 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

  1. Você → GitHub: git push. Você envia o commit. Para o GitHub, isso é um evento que pode disparar workflows.
  2. GitHub → CI: Dispara o workflow. O gatilho on: push acorda um runner, que baixa o código.
  3. CI → CI: lint, testes, build. A conferência. Se algo falha aqui, o fluxo para e o site antigo continua no ar, intacto.
  4. CI → Hospedagem: Envia a pasta dist/. Com tudo verde, só o resultado do build é publicado, não o código-fonte inteiro.
  5. 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 main publica 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ê (steps com uses e run).
  • 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).

  1. Crie .github/workflows/ci.yml rodando instalação, lint, testes e build em cada pull request
  2. Abra um PR com um teste quebrado de propósito e leia o log da falha até achar a linha do erro
  3. Corrija, envie de novo e veja o status ficar verde
  4. Publique o site (ou o relatório de testes) no GitHub Pages, Netlify ou Vercel
  5. Escreva no README como rodar o projeto localmente e como voltar para a versão anterior publicada

Referências

Cursos relacionados