From 86cbe8e43159ae3c42335df962a8fbe91dbed40d Mon Sep 17 00:00:00 2001 From: joelson brito Date: Fri, 14 Nov 2025 17:24:38 -0300 Subject: [PATCH] =?UTF-8?q?feat:=20adiciona=20sistema=20de=20versionamento?= =?UTF-8?q?=20e=20releases=20autom=C3=A1ticas?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Implementa versionamento semântico para imagens Docker - Adiciona job de release automática no GitHub Actions - Releases criadas apenas para tags na branch main - Adiciona documentação de versionamento em docs/VERSIONAMENTO.md - Suporte a tags semânticas (v0.1.0, v0.5.0, etc) - Versionamento baseado em package.json e tags Git --- .github/workflows/ci.yml | 85 +++++++++++++++++++++++++- docs/VERSIONAMENTO.md | 127 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 211 insertions(+), 1 deletion(-) create mode 100644 docs/VERSIONAMENTO.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d22731..fafe7e2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,6 +3,8 @@ name: CI on: push: branches: [ main, master, develop, homologacao ] + tags: + - 'v*' pull_request: branches: [ main, master, develop, homologacao ] @@ -148,6 +150,13 @@ jobs: username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} + - name: Get package version + id: package-version + run: | + VERSION=$(node -p "require('./package.json').version") + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "Package version: $VERSION" + - name: Extract metadata id: meta uses: docker/metadata-action@v5 @@ -156,8 +165,12 @@ jobs: tags: | type=ref,event=branch type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=semver,pattern={{major}} type=sha,prefix={{branch}}- - type=raw,value=latest,enable={{is_default_branch}} + type=raw,value=${{ steps.package-version.outputs.version }},enable=${{ github.ref_type == 'branch' }} + type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }} - name: Build and push Docker image uses: docker/build-push-action@v5 @@ -169,3 +182,73 @@ jobs: labels: ${{ steps.meta.outputs.labels }} cache-from: type=gha cache-to: type=gha,mode=max + + release: + name: Create Release + runs-on: ubuntu-latest + needs: [build, docker-build] + if: startsWith(github.ref, 'refs/tags/v') && github.ref_type == 'tag' + permissions: + contents: write + + env: + REGISTRY: ghcr.io + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + fetch-tags: true + + - name: Check if tag is on main branch + id: check-branch + run: | + git fetch origin main:main 2>/dev/null || true + if git branch -r --contains ${{ github.ref_name }} | grep -q 'origin/main'; then + echo "on_main=true" >> $GITHUB_OUTPUT + echo "Tag is on main branch" + else + echo "on_main=false" >> $GITHUB_OUTPUT + echo "Tag is not on main branch, skipping release" + fi + + - name: Get version from tag + id: version + run: | + TAG_VERSION=${GITHUB_REF#refs/tags/v} + echo "version=$TAG_VERSION" >> $GITHUB_OUTPUT + echo "Tag version: $TAG_VERSION" + + - name: Generate changelog + id: changelog + run: | + PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "") + if [ -z "$PREVIOUS_TAG" ]; then + CHANGELOG=$(git log --pretty=format:"- %s (%h)" HEAD) + else + CHANGELOG=$(git log --pretty=format:"- %s (%h)" ${PREVIOUS_TAG}..HEAD) + fi + echo "changelog<> $GITHUB_OUTPUT + echo "$CHANGELOG" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + + - name: Create Release + if: steps.check-branch.outputs.on_main == 'true' + uses: softprops/action-gh-release@v1 + with: + tag_name: ${{ github.ref_name }} + name: Release ${{ steps.version.outputs.version }} + body: | + ## Versão ${{ steps.version.outputs.version }} + + ### Mudanças + ${{ steps.changelog.outputs.changelog }} + + ### Docker Image + ```bash + docker pull ${{ env.REGISTRY }}/${{ github.repository }}:${{ steps.version.outputs.version }} + docker pull ${{ env.REGISTRY }}/${{ github.repository }}:latest + ``` + draft: false + prerelease: false diff --git a/docs/VERSIONAMENTO.md b/docs/VERSIONAMENTO.md new file mode 100644 index 0000000..0335198 --- /dev/null +++ b/docs/VERSIONAMENTO.md @@ -0,0 +1,127 @@ +# Sistema de Versionamento + +Este documento descreve o sistema de versionamento utilizado no projeto, incluindo como as imagens Docker são versionadas e como criar releases no GitHub. + +## Visão Geral + +O projeto utiliza versionamento semântico baseado no arquivo `package.json` e tags Git para gerenciar versões de imagens Docker e releases no GitHub Container Registry (GHCR). + +## Versionamento de Imagens Docker + +As imagens Docker são automaticamente versionadas durante o processo de CI/CD baseado no contexto do push: + +### Branches + +- **Branch `homologacao`**: `ghcr.io/usuario/repo:homologacao` +- **Branch `main`**: + - `ghcr.io/usuario/repo:main` + - `ghcr.io/usuario/repo:latest` + - `ghcr.io/usuario/repo:{versao-do-package.json}` + +### Tags Git + +Quando uma tag é criada (formato `v*`, exemplo: `v0.1.0`), as seguintes tags são geradas: + +- `ghcr.io/usuario/repo:0.1.0` (versão completa) +- `ghcr.io/usuario/repo:0.1` (major.minor) +- `ghcr.io/usuario/repo:0` (major) + +### Commits + +Cada commit gera uma tag com o SHA do commit: +- `ghcr.io/usuario/repo:{branch}-{sha}` + +## Releases no GitHub + +Releases são criadas automaticamente quando uma tag Git no formato `v*` é enviada para a branch `main`. O processo inclui: + +1. Verificação se a tag está na branch `main` +2. Geração automática de changelog baseado nos commits desde a última tag +3. Criação da release no GitHub com: + - Nome da versão + - Changelog completo + - Instruções para download da imagem Docker + +## Como Criar uma Nova Versão + +### Para Homologação + +1. Atualize a versão no `package.json`: + +```bash +npm version patch # Incrementa patch: 0.0.1 -> 0.0.2 +npm version minor # Incrementa minor: 0.0.1 -> 0.1.0 +npm version major # Incrementa major: 0.0.1 -> 1.0.0 +``` + +2. Faça commit e push: + +```bash +git add package.json package-lock.json +git commit -m "chore: bump version to 0.1.0" +git push origin homologacao +``` + +A imagem Docker será automaticamente buildada e publicada com a tag correspondente à branch. + +### Para Produção (Release) + +1. Faça merge da branch `homologacao` para `main`: + +```bash +git checkout main +git merge homologacao +``` + +2. Crie uma tag e faça push: + +```bash +git tag v0.1.0 +git push origin main --tags +``` + +Este processo irá: + +- Buildar a imagem Docker com as tags de versão semântica +- Criar automaticamente uma release no GitHub +- Publicar a imagem no GitHub Container Registry + +## Verificar Versão Atual + +A versão atual do projeto está definida no arquivo `package.json`: + +```json +{ + "version": "0.0.1" +} +``` + +## Estrutura de Tags Docker + +As imagens Docker seguem o seguinte padrão de nomenclatura: + +- **Desenvolvimento**: `{registry}/{repo}:{branch-name}` +- **Versão específica**: `{registry}/{repo}:{version}` (ex: `0.1.0`) +- **Versão parcial**: `{registry}/{repo}:{major}.{minor}` (ex: `0.1`) +- **Major version**: `{registry}/{repo}:{major}` (ex: `0`) +- **Latest**: `{registry}/{repo}:latest` (apenas branch main) +- **Commit SHA**: `{registry}/{repo}:{branch}-{sha}` + +## Workflow de CI/CD + +O workflow de CI/CD está configurado no arquivo `.github/workflows/ci.yml` e executa os seguintes jobs: + +1. **Lint**: Verificação de código e formatação +2. **Build**: Compilação do projeto TypeScript +3. **Test**: Execução de testes unitários +4. **Test E2E**: Execução de testes end-to-end (apenas PRs e main) +5. **Docker Build**: Build e push da imagem Docker +6. **Release**: Criação de release no GitHub (apenas tags na main) + +## Notas Importantes + +- Tags devem seguir o formato semântico: `v{major}.{minor}.{patch}` (ex: `v1.0.0`) +- Releases são criadas apenas para tags na branch `main` +- A versão no `package.json` é usada para versionar imagens em branches +- Tags Git são usadas para versionar imagens em releases de produção +