Como Configurar CI/CD com GitHub Actions: Tutorial Completo

Resumo Executivo

Objetivo: Configurar pipeline completo de CI/CD que executa testes automaticamente, faz build da aplicação e deploy para produção quando código é enviado para branch main.

Tempo Estimado: 45-60 minutos para implementação completa. Pré-requisitos: Repositório GitHub, conhecimento básico de Git e familiaridade com linha de comando.

GitHub Actions transformou como desenvolvedores implementam CI/CD, oferecendo automação poderosa diretamente integrada ao GitHub. Em 2025, dominar GitHub Actions é essencial para qualquer desenvolvedor que busca workflows modernos e eficientes.

Este tutorial hands-on vai te ensinar a criar pipelines robustos de CI/CD que automatizam todo o processo, desde testes até deploy em produção. Vamos implementar juntos um workflow real que você pode adaptar para seus projetos.

Pré-requisitos e Setup Inicial

O que Você Vai Precisar

Repositório GitHub: Público ou privado (2000 min/mês gratuitos para privados)
Projeto Node.js: Com package.json e scripts de test/build configurados
Provider de Deploy: Vercel, Netlify, AWS, ou similar (vamos usar Vercel neste tutorial)
Editor de Código: VSCode ou similar com syntax highlighting para YAML

Estrutura do Projeto de Exemplo

Vamos trabalhar com uma aplicação React típica:

Arquivo	Propósito	Comando
package.json	Scripts e dependências	npm test, npm run build
src/	Código fonte	Componentes React
__tests__/	Testes automatizados	Jest + Testing Library
.github/workflows/	Workflows do GitHub Actions	Arquivos YAML

Passo 1: Criando Seu Primeiro Workflow

1.1 Estrutura Básica do Arquivo YAML

Crie o arquivo .github/workflows/ci-cd.yml no seu repositório:

ci-cd.yml - Estrutura Base

name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout código
      uses: actions/checkout@v4
      
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
        cache: 'npm'
        
    - name: Instalar dependências
      run: npm ci
      
    - name: Executar testes
      run: npm test -- --coverage --watchAll=false

1.2 Entendendo a Estrutura

name: Nome do workflow que aparece na interface do GitHub
on: Eventos que disparam o workflow (push, PR, schedule, etc.)
jobs: Conjunto de steps que executam em paralelo ou sequência
runs-on: Sistema operacional do runner (ubuntu-latest, windows-latest, macos-latest)
steps: Ações individuais executadas no job

Passo 2: Configurando Testes Automatizados

2.1 Matrix Strategy para Múltiplas Versões

Teste sua aplicação em diferentes versões do Node.js:

Matrix Testing

test:
  runs-on: ubuntu-latest
  
  strategy:
    matrix:
      node-version: [16, 18, 20]
      
  steps:
  - uses: actions/checkout@v4
  
  - name: Setup Node.js ${{ matrix.node-version }}
    uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node-version }}
      cache: 'npm'
      
  - run: npm ci
  - run: npm test -- --coverage --watchAll=false
  
  - name: Upload coverage para Codecov
    uses: codecov/codecov-action@v3
    with:
      file: ./coverage/lcov.info

2.2 Configurando Diferentes Tipos de Teste

Testes Essenciais

Unit Tests: Jest + Testing Library para componentes
Linting: ESLint para qualidade de código
Type Checking: TypeScript (se aplicável)
Security Audit: npm audit para vulnerabilidades

Testes Avançados

E2E Tests: Playwright ou Cypress
Performance: Lighthouse CI
Accessibility: axe-core testing
Visual Regression: Percy ou Chromatic

Passo 3: Implementando Build e Deploy

3.1 Job de Build com Artifacts

Separe build de deploy para melhor organização:

Build Job

build:
  needs: test
  runs-on: ubuntu-latest
  
  steps:
  - uses: actions/checkout@v4
  
  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '18'
      cache: 'npm'
      
  - run: npm ci
  - run: npm run build
  
  - name: Upload build artifacts
    uses: actions/upload-artifact@v4
    with:
      name: build-files
      path: build/
      retention-days: 7

3.2 Deploy Condicional para Produção

Deploy Job

deploy:
  needs: build
  runs-on: ubuntu-latest
  if: github.ref == 'refs/heads/main'
  
  environment:
    name: production
    url: https://minha-app.vercel.app
    
  steps:
  - uses: actions/checkout@v4
  
  - name: Download build artifacts
    uses: actions/download-artifact@v4
    with:
      name: build-files
      path: build/
      
  - name: Deploy para Vercel
    uses: amondnet/vercel-action@v25
    with:
      vercel-token: ${{ secrets.VERCEL_TOKEN }}
      vercel-org-id: ${{ secrets.ORG_ID }}
      vercel-project-id: ${{ secrets.PROJECT_ID }}
      vercel-args: '--prod'

Passo 4: Configurando Secrets e Variáveis

4.1 Adicionando Secrets no GitHub

Vá para Settings → Secrets and variables → Actions
Clique em "New repository secret"
Adicione os secrets necessários:

Secret Name	Descrição	Como Obter
VERCEL_TOKEN	Token de acesso do Vercel	Vercel Dashboard → Settings → Tokens
ORG_ID	ID da organização	Vercel CLI: vercel org
PROJECT_ID	ID do projeto	Arquivo .vercel/project.json

4.2 Usando Environments para Proteção

Configure environments para adicionar aprovações manuais:

Repository Settings → Environments
Criar environment "production"
Adicionar Required reviewers (opcional)
Configurar Protection rules para branches específicas

Passo 5: Workflow Completo Integrado

5.1 Arquivo Final ci-cd.yml

Workflow Completo

name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

env:
  NODE_VERSION: '18'

jobs:
  test:
    name: Test & Lint
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [16, 18, 20]
        
    steps:
    - name: Checkout
      uses: actions/checkout@v4
      
    - name: Setup Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Run linter
      run: npm run lint
      
    - name: Run tests
      run: npm test -- --coverage --watchAll=false
      
    - name: Upload coverage
      uses: codecov/codecov-action@v3
      if: matrix.node-version == 18

  build:
    name: Build Application
    needs: test
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ env.NODE_VERSION }}
        cache: 'npm'
        
    - run: npm ci
    - run: npm run build
    
    - name: Upload build artifacts
      uses: actions/upload-artifact@v4
      with:
        name: build-${{ github.sha }}
        path: build/

  deploy-staging:
    name: Deploy to Staging
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/develop'
    
    environment:
      name: staging
      url: https://staging-minha-app.vercel.app
      
    steps:
    - uses: actions/checkout@v4
    
    - name: Download artifacts
      uses: actions/download-artifact@v4
      with:
        name: build-${{ github.sha }}
        path: build/
        
    - name: Deploy to Vercel
      uses: amondnet/vercel-action@v25
      with:
        vercel-token: ${{ secrets.VERCEL_TOKEN }}
        vercel-org-id: ${{ secrets.ORG_ID }}
        vercel-project-id: ${{ secrets.PROJECT_ID }}

  deploy-production:
    name: Deploy to Production
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    environment:
      name: production
      url: https://minha-app.vercel.app
      
    steps:
    - uses: actions/checkout@v4
    
    - name: Download artifacts
      uses: actions/download-artifact@v4
      with:
        name: build-${{ github.sha }}
        path: build/
        
    - name: Deploy to Production
      uses: amondnet/vercel-action@v25
      with:
        vercel-token: ${{ secrets.VERCEL_TOKEN }}
        vercel-org-id: ${{ secrets.ORG_ID }}
        vercel-project-id: ${{ secrets.PROJECT_ID }}
        vercel-args: '--prod'

Passo 6: Monitoramento e Otimização

6.1 Configurando Notificações

Adicione notificações para Slack ou Discord em caso de falha:

Notificação Slack

- name: Notify Slack on failure
  if: failure()
  uses: 8398a7/action-slack@v3
  with:
    status: failure
    channel: '#dev-team'
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}

6.2 Cache Estratégico para Performance

Node modules: Use cache automático do setup-node
Build cache: Cache de build entre runs
Docker layers: Para workflows com containers
Dependency cache: Yarn/pnpm specific caching

Troubleshooting e Boas Práticas

Problemas Comuns e Soluções

Problemas Frequentes

Jobs falham por falta de permissões
Secrets não são reconhecidos
Cache não está funcionando
Deploy falha por timeout
Testes flaky causam falsos negativos

Soluções

Configurar GITHUB_TOKEN com permissões adequadas
Verificar nomes de secrets (case-sensitive)
Usar cache-dependency-path específico
Aumentar timeout-minutes nos steps
Implementar retry logic para testes

Boas Práticas de Segurança

Princípio do Menor Privilégio: Tokens com mínimas permissões necessárias
Environment Protection: Aprovações manuais para produção
Secret Rotation: Renovar tokens regularmente
Audit Logs: Monitorar execuções e acessos
Branch Protection: Require status checks antes de merge

Monitoramento e Métricas

KPIs Importantes

Métrica	Objetivo	Como Medir
Tempo de Build	< 10 minutos	Actions dashboard
Taxa de Sucesso	> 95%	Workflow history
Time to Production	< 30 minutos	Commit to deploy
Coverage de Testes	> 80%	Coverage reports

Próximos Passos e Extensões

Funcionalidades Avançadas

Multi-environment deploys: Staging, QA, Production
Feature flag integration: LaunchDarkly, Split.io
Database migrations: Automated schema updates
Performance monitoring: Lighthouse, Web Vitals
Security scanning: Snyk, OWASP dependency check

Integrações Úteis

Jira/Linear: Automatic ticket updates
Sentry: Error tracking integration
DataDog: APM and monitoring
Terraform: Infrastructure as Code

Implemente CI/CD no Seu Projeto

Automatize seu workflow de desenvolvimento hoje mesmo. Comece com este template e adapte para suas necessidades específicas.

Ver Mais Tutoriais DevOps →

Perguntas Frequentes

GitHub Actions é gratuito para repositórios privados? +

GitHub Actions oferece 2000 minutos gratuitos mensais para contas privadas. Repositórios públicos têm uso ilimitado. Para uso intenso, planos pagos oferecem minutos adicionais.

Como configurar deploy automático apenas na branch main? +

Use 'on: push: branches: [main]' no workflow para executar apenas em pushes para main. Adicione condicionais como 'if: github.ref == 'refs/heads/main'' para steps específicos de deploy.

É possível usar GitHub Actions com outros provedores de nuvem? +

Sim, GitHub Actions suporta deploy para AWS, Google Cloud, Azure, Vercel, Netlify e outros. Use actions oficiais de cada provedor ou configure credenciais via secrets.

Como debuggar workflows que estão falhando? +

Use logs detalhados no Actions tab, adicione steps de debug com 'echo' commands, habilite step debugging com 'ACTIONS_STEP_DEBUG: true', e teste workflows localmente com act.

Qual a diferença entre jobs e steps no GitHub Actions? +

Jobs executam em paralelo em runners separados, steps executam sequencialmente dentro de um job. Use jobs para tarefas independentes (test, build, deploy) e steps para ações sequenciais.

Como implementar aprovações manuais antes do deploy? +

Configure environments no repositório (Settings → Environments), adicione required reviewers, e use 'environment: production' no job de deploy. O workflow aguardará aprovação antes de continuar.