Pular para conteúdo

Versionamento e releases

O EcomSmart Flow usa Semantic Versioning independente para os canais de staging e produção. O tipo da versão é definido pelo início do título do Merge Request.

Modo temporário: trunk-based

Enquanto HML permanece desligada, RELEASE_WORKFLOW=trunk é o padrão do YAML. Branches de trabalho partem de main e abrem MR diretamente para ela. Revisão, testes e título SemVer continuam obrigatórios; deploy permanece manual.

branch de trabalho → MR para main → testes e revisão → merge
  → testes do commit integrado → flow_build_all_images
  → publish_production_version → deploy_production manual
  → verify_production_stability

No modo trunk, as imagens são construídas com o SHA final da main, incluindo merge ou squash. A publicação espera o build e promove esse mesmo SHA. Não usa o SHA da ponta da branch de trabalho. Push direto sem MR associado não gera release automaticamente; mantenha as proteções da branch.

Título do MR Incremento Exemplo
fix: ... patch 0.0.1 para 0.0.2
feat: ... minor 0.0.1 para 0.1.0
breaking change: ... major 0.0.1 para 1.0.0

feat!: ... e fix!: ... também são tratados como breaking changes. Outros prefixos são recusados nos MRs destinados a develop ou main.

Canais

  • merge para develop: v0.1.0-staging.<CI_PIPELINE_IID>;
  • merge de qualquer branch para main em trunk: v0.1.0;
  • no modo promotion, somente develop pode abrir release para main;
  • staging e produção mantêm sequências SemVer independentes;
  • todas as imagens de uma release recebem a mesma tag;
  • as imagens continuam disponíveis também pelo SHA imutável de origem.

O job não reconstrói imagens ao promover uma versão. Ele usa skopeo para copiar, no próprio Registry, os manifests que já foram publicados com o SHA. No modo trunk, produção usa o SHA integrado da main, construído na mesma pipeline. No modo promotion, usa o SHA da ponta da develop registrada no MR, promovendo exatamente o artefato preparado para staging, sem rebuild.

Jobs

  • release_title_policy: valida o título e a direção do MR;
  • release_versioning_tests: testa as regras SemVer;
  • publish_staging_version: promove as imagens e cria a tag de staging;
  • publish_production_version: promove as imagens e cria a tag de produção.

O runner dedicado flow-build constrói e publica todas as imagens no Registry com o SHA imutável do commit. Quando ENABLE_AUTOMATIC_RELEASES=true, o job de publicação promove essas imagens para a versão SemVer do canal somente depois que o build termina com sucesso.

Para habilitar esse encadeamento automático, cadastre:

ENABLE_AUTOMATIC_RELEASES=true

O deploy permanece manual: uma release nova não altera o cluster até que um responsável execute deploy_staging ou deploy_production. Producao exige ambiente protegido e o checklist de docs/production-deployment.md.

O build de imagens não é oferecido em pipelines de Merge Request. Nos MRs são executados somente testes e validações; o build oficial começa depois do merge na main em trunk ou na develop em promotion, usando o SHA que será versionado.

Retorno ao fluxo com homologação

  1. Preparar HML com dados e integrações separados.
  2. Sincronizar develop com as alterações feitas diretamente na main, por MR.
  3. Garantir build e validação do estado que será promovido.
  4. Alterar RELEASE_WORKFLOW para promotion de forma coordenada, sem releases em andamento.
  5. Comunicar que novos MRs de trabalho voltam a ter destino develop.

Essa seleção pode ser versionada no YAML ou definida como variável protegida no GitLab, com escopo *, pois participa das rules. Não usar escopo apenas production para selecionar o modo da pipeline. Usar exatamente trunk ou promotion; outros valores são rejeitados pelo versionamento.

develop continua podendo gerar staging no modo trunk, mas não é etapa obrigatória da entrega e isso não reativa HML automaticamente.

Configuração necessária no GitLab

  1. Proteja as branches develop e main.
  2. Em Settings > CI/CD > Job token permissions, habilite Allow Git push requests to the repository.
  3. Proteja as tags v* e permita que os responsáveis pelas releases as criem.
  4. Cadastre ENABLE_AUTOMATIC_RELEASES=true somente depois de validar o runner dedicado flow-build.

O push feito com CI_JOB_TOKEN não inicia outro pipeline. O job é idempotente: se o commit já possuir a tag daquele canal, uma nova versão não é criada.

Procedimento de contingência

Se o runner dedicado estiver indisponível, mantenha ENABLE_AUTOMATIC_RELEASES=false e, depois do merge em main no modo trunk, publique as imagens manualmente (em promotion, usar a develop):

git switch main
git pull --ff-only origin main
$tag = (git rev-parse HEAD).Trim()
./deploy/kubernetes/scripts/build-images.ps1 -Tag $tag -Push

Depois execute manualmente publish_production_version em trunk, ou publish_staging_version em promotion. O deploy recebe RELEASE_IMAGE_TAG pelo relatório dotenv e usa a versão promovida. Em uma pipeline normal de trunk, execute build antes da publicação manual. Para rollback, continue usando uma pipeline manual da main com ROLLBACK_IMAGE_TAG=X.Y.Z e o job rollback_production, sem build/nova release.

Pipelines iniciados manualmente pela interface do GitLab (web) também exibem os jobs manuais de build e release quando executados em develop ou main.