Guia passo a passo para implementar CI/CD com GitHub Actions em projetos PHP/Laravel

Por · Publicado em · Atualizado em · 8 min de leitura

Notebook em mesa com editor de código aberto na tela e monitor ao fundo
Workspace com código na tela, adequado para guias de CI/CD e workflows Foto: yeiferr / Pixabay

Este guia passo a passo mostra como implementar CI/CD com GitHub Actions em projetos PHP/Laravel. Você vai entender gatilhos, jobs, cache, testes, segurança de secrets e estratégias de deploy para staging e produção. Ao final, terá um roteiro claro para configurar um pipeline confiável, com dicas práticas de manutenção e rollback.

Visão geral do pipeline e pré‑requisitos

CI/CD integra validações automáticas a cada mudança e entrega versões de forma previsível. Em Laravel, o pipeline costuma incluir instalação de dependências, build de assets, testes e deploy com comandos artisan.

Defina o objetivo do pipeline antes de escrever qualquer workflow. Decida o que roda em cada branch, quando aprovar manualmente e como será o deploy para staging e produção.

Padronize versões de PHP e extensões. Documente as dependências do sistema. Confirme o banco de dados necessário nos testes. Evite surpresas no runner.

Crie ambientes previsíveis. Use variáveis, secrets e um processo de versionamento consistente. Isso diminui diferenças entre sua máquina e o CI.

  • Acesso ao repositório no GitHub e branches principais definidos.
  • composer.json e composer.lock versionados.
  • phpunit.xml configurado e testes que rodam em segundos a poucos minutos.
  • Servidor ou PaaS para deploy via SSH, API ou container registry.
  • Banco de dados de testes provisionado (MySQL, PostgreSQL ou SQLite).
  • Estratégia de versionamento e releases definida.

Prepare o projeto: Composer, scripts e ambientes

Garanta que composer.lock esteja versionado. Isso torna builds reproduzíveis. Instale extensões mínimas e desative Xdebug no CI para acelerar o pipeline.

Crie scripts no composer.json para padronizar comandos. Centralize testes, linters e análise estática. Assim, o CI apenas chama scripts já usados localmente.

Mantenha .env.example completo. Ele serve de base para gerar ambientes de teste. Nunca versione credenciais reais. APP_KEY deve ser injetada via secret.

Ative caches do Laravel em produção para melhor desempenho. Use config:cache, route:cache e view:cache. Consulte a documentação de configuração do Laravel para detalhes.

  • scripts.test: vendor/bin/phpunit
  • scripts.analyse: vendor/bin/phpstan analyse
  • scripts.lint: vendor/bin/php-cs-fixer fix --dry-run --diff
  • scripts.post-deploy: php artisan optimize && php artisan migrate --force

Crie o workflow no GitHub Actions

Crie o arquivo .github/workflows/ci.yml. Use on: push e on: pull_request para validar novas alterações. Configure uma matriz de versões de PHP, se necessário.

Escolha ubuntu-latest como runner e instale PHP com extensões. Use cache do Composer apontando para composer.lock. Isso reduz tempo de instalação.

Se seus testes exigem banco, use serviços do runner. Suba MySQL ou PostgreSQL como service e rode migrations antes dos testes.

Separe jobs por objetivo. Exemplo: build e testes em um job; análise estática em outro; deploy em job condicionado a branch e aprovação do ambiente.

Etapa Objetivo Exemplos de comandos
Setup PHP Definir versão e extensões Instalar PHP 8.2/8.3, intl, mbstring, pdo, pdo_mysql/pdo_pgsql
Cache Composer Acelerar dependências composer install --prefer-dist --no-interaction --no-progress
Provisionar DB Preparar testes Criar banco, php artisan key:generate, migrations
Testes Validar código vendor/bin/phpunit --colors=never
Análise estática Detectar erros cedo vendor/bin/phpstan analyse
Lint Padronizar estilo vendor/bin/php-cs-fixer fix --dry-run
Deploy Entregar com controle php artisan down/up, migrate --force, optimize

Testes, qualidade e cobertura

Execute testes rápidos e confiáveis. Priorize unidade e integração com SQLite em memória quando viável. Isso diminui custos e falhas intermitentes.

Use relatórios de cobertura quando fizer sentido. Cobertura não garante qualidade, mas ajuda a identificar áreas sem testes.

Adote análise estática com PHPStan ou Psalm. Elas encontram erros de tipo e contratuais antes de ir para produção.

Padronize estilo com PHP-CS-Fixer ou PHPCS. Código consistente facilita revisões e reduz conflitos.

  • Teste o domínio sem acessar rede desnecessariamente.
  • Evite testes frágeis que dependem de datas e timeouts.
  • Marque testes lentos e rode-os apenas em pushes para main.
  • Falhas devem bloquear merge em pull requests.

Segurança: secrets, permissões e isolamento

Nunca versione credenciais. Use GitHub Actions secrets para APP_KEY, credenciais de banco, chaves SSH e tokens de deploy. Restrinja acesso por ambiente.

Aplique princípio do menor privilégio. Crie usuários específicos para deploy com permissões limitadas. Evite chaves reutilizadas.

Masque saídas sensíveis nos logs. Desative eco de variáveis críticas. Revogue e rotacione credenciais periodicamente.

Considere OpenID Connect para autenticar em provedores de nuvem sem chaves persistentes. Isso reduz risco de vazamento.

  • Segregue staging e produção com secrets e ambientes distintos.
  • Exija revisão ou aprovação para promover a produção.
  • Audite quem pode ver e editar secrets no repositório.
  • Evite echo de variáveis sensíveis em steps do workflow.

Deploy contínuo: staging e produção com segurança

Crie ambientes no GitHub (staging e production) com proteção e aprovação. O deploy só inicia se os jobs de qualidade passarem.

Defina estratégia de empacotamento. Você pode gerar artefato com vendor e assets já compilados, ou construir no servidor. Artefatos reduzem variações.

No deploy, use janelas previsíveis. Em Laravel, execute config:cache, route:cache e view:cache. Em seguida, rode migrations com --force.

Para zero‑downtime, use releases versionadas com symlink para current. Publique uma nova pasta release, rode migrations e aponte o symlink para ela.

Trabalha com queues? Reinicie workers após o deploy. Em Laravel Horizon, use horizon:terminate para recarregar código sem parar a fila.

  • Ordem sugerida: colocar site em manutenção, publicar artefato, executar migrations, limpar caches específicos, sair de manutenção.
  • Faça rollback fácil mantendo 3 a 5 releases anteriores.
  • Automatize verificação de saúde após deploy com uma rota de status.
  • Considere Docker para padronizar runtime, especialmente em times maiores.

Observabilidade, rollback e continuidade

Monitore métricas e logs para confirmar o sucesso do deploy. Alerts ajudam a agir rápido quando algo degrada.

Implemente health checks e um teste de fumaça automatizado após o deploy. Se falhar, dispare rollback para a release anterior.

Mantenha backups consistentes do banco e dos arquivos críticos antes de mudanças sensíveis. Isso reduz impacto em incidentes.

  • Centralize logs de aplicação e servidor.
  • Rastreie versão do commit e número da release em headers.
  • Crie playbooks de rollback e teste-os regularmente.
  • Integre alertas com chat ou e-mail da equipe.

Erros comuns e checklist final

Alguns problemas se repetem em pipelines novos. Mapear antecipadamente acelera a estabilização e evita incidentes desnecessários.

Use esta checklist para validar os pontos essenciais antes de habilitar deploy automático para produção.

  • Erros comuns: não versionar composer.lock; esquecer APP_KEY no ambiente; rodar migrations sem backup; dependências do SO não instaladas; pipelines lentos por falta de cache.
  • Checklist: gatilhos definidos; matrix de PHP testada; cache do Composer ativo; banco de testes provisionado; secrets configurados; ambientes com aprovação; script de deploy idempotente; rollback documentado.

Perguntas frequentes

Como lidar com banco de dados em deploys automatizados?

Execute migrations com --force apenas após passar por testes e backups. Em mudanças arriscadas, use migrações compatíveis com versões antigas. Tenha scripts de rollback quando possível. Para zero‑downtime, separe passos que bloqueiam tabelas em janelas controladas.

Preciso usar Docker para CI/CD no GitHub Actions?

Não é obrigatório. Docker ajuda a padronizar o ambiente e facilita reproduzir problemas. Para projetos menores, runners hospedados e serviços de banco costumam ser suficientes. Avalie Docker quando o setup local ou do servidor variar muito entre máquinas.

Como otimizar o tempo do pipeline?

Ative cache do Composer baseado no arquivo lock, desabilite Xdebug, isole testes lentos, rode análise estática em paralelo e baixe dependências em modo prefer-dist. Evite builds de assets desnecessários em pull requests que não tocam front-end.

É seguro guardar APP_KEY nos secrets do GitHub?

Usar secrets do GitHub é recomendado, desde que com acesso restrito por ambiente e revisão de permissões. Não registre logs com o valor. Rotacione periodicamente. Para PaaS, prefira injetar a variável diretamente no provedor, sem expô-la no repositório.

Como separar staging e produção no workflow?

Crie dois ambientes no GitHub com secrets distintos e exigência de aprovação para produção. Condicione o job de deploy ao branch correspondente, como main para produção e develop para staging. Opcionalmente, publique artefatos diferentes por ambiente.

Posso usar runners auto-hospedados para o deploy?

Pode. Runners auto-hospedados dão controle total sobre dependências e rede. Exigem manutenção e segurança adicional. Restrinja permissões, mantenha o sistema atualizado e isole projetos. Use-os quando precisar acessar recursos privados sem expor chaves.

Pronto para configurar seu pipeline CI/CD?

Quer acelerar a implementação de CI/CD com GitHub Actions em PHP/Laravel ou revisar seu pipeline atual? Vamos conversar sobre seu contexto e próximos passos.

Falar sobre meu pipeline

Veja também