doczyai-pipelines/documentation/release-rollback-strategy.md

CI/CD Branching, Promotion, Release, and Rollback Strategy

This document describes the current Bitbucket CI/CD implementation and branch governance configured for this repository. It reflects the intended promotion model shown in the attached strategy image.

1) Strategy Overview

Branch model

• feature/* and bugfix/* are short-lived development branches.
• dev is the integration branch.
• stg is the pre-production validation branch.
• main is the production release branch.
• hotfix/* supports emergency fixes with controlled promotion.

Promotion paths (as implemented)

1. feature/* -> Develop
2. bugfix/* -> Develop
3. dev -> Staging
4. stg -> main

Hotfix paths

• hotfix/* -> main (direct emergency production fix)
• hotfix/* -> dev (back-merge / forward-fix alignment)

2) Pull Request Pipeline Controls

Defined under pipelines.pull-requests in bitbucket-pipelines.yml.

A. Source branch gate by pattern

• feature/*: pipeline fails unless destination is dev
• bugfix/*: pipeline fails unless destination is dev
• hotfix/*: pipeline fails unless destination is main or dev
• dev: pipeline fails unless destination is stg
• stg: pipeline fails unless destination is main

B. Branch naming validation for all PRs

The "**" PR pipeline validates source branch naming convention:

• Allowed: feature/<description>
• Allowed: bugfix/<description>
• Allowed: hotfix/<description>

Any other source branch naming pattern is blocked.

3) Repository Branch Restrictions (Bitbucket Settings)

The following controls are enforced through repository settings (in addition to pipeline checks).

3.1 dev

• Direct write access: restricted
• Deletion: not allowed
• History rewrite: not allowed
• Merge via PR only
• Merge checks:
  • minimum 1 approval
  • minimum 1 default reviewer approval
  • unresolved PR tasks not allowed
  • last commit must have successful build

3.2 stg

• Direct write access: restricted
• Deletion: not allowed
• History rewrite: not allowed
• Merge via PR only
• Merge checks:
  • minimum 2 approvals
  • minimum 1 default reviewer approvals
  • unresolved PR tasks not allowed
  • last commit must have successful build

3.3 main

• Direct write access: restricted
• Deletion: not allowed
• History rewrite: not allowed
• Merge via PR only
• Merge checks:
  • minimum 2 approvals
  • minimum 1 default reviewer approvals
  • unresolved PR tasks not allowed
  • last commit must have successful build

3.4 feature/*

• Write access: broader (Everybody)
• Deletion: not allowed
• History rewrite: not allowed
• Merge to protected branches is still controlled by PR destination branch restrictions and PR pipeline gates.

3.5 bugfix/*

• Write access: limited to authorized users/groups
• Deletion: not allowed
• History rewrite: not allowed

3.6 hotfix/*

• Write access: limited to authorized users
• Deletion: not allowed
• History rewrite: not allowed
• PR merges additionally require build success and at least 1 approval (as configured).

4) End-to-End Flow (Aligned to Strategy Image)

flowchart LR
    FB[feature/* or bugfix/*] -->|PR + checks| D[dev]
    D -->|PR + stricter checks| S[stg]
    S -->|PR + strictest checks| M[main]
    H[hotfix/*] -->|PR + checks| M
    H -->|PR + checks| D

Control layering

Each promotion is protected by two layers:

1. Pipeline gate validates source/destination path and syntax/build health.
2. Branch restriction gate enforces approvals, reviewers, task completion, and successful build before merge.

5) Release to Production (Custom Pipeline)

Custom pipeline: release-prod

Behavior

1. Enforces execution from main only.
2. Reads latest tag matching v*.
3. Calculates next version using RELEASE_TYPE:
   • major: increments major, resets minor/patch to 0.
   • minor: increments minor, resets patch to 0.
4. Creates and pushes annotated tag.
5. Deploys using repository variable DEPLOY_COMMAND with RELEASE_TAG.

Inputs

• RELEASE_TYPE (major or minor, default minor)

Required variable

• DEPLOY_COMMAND (must consume RELEASE_TAG)

6) Rollback in Production (Custom Pipeline)

Custom pipeline: rollback-prod

Behavior

1. Enforces execution from main only.
2. Validates ROLLBACK_TAG is provided.
3. Validates tag exists in repository.
4. Re-deploys by setting RELEASE_TAG=ROLLBACK_TAG and executing DEPLOY_COMMAND.

Input

• ROLLBACK_TAG (example: v2.3.0)

7) Operational Notes

• Branch names in pipeline checks are case-sensitive; current gates use Develop and Staging (capitalized).
• Branch restriction and pipeline branch names must remain consistent to avoid false gate failures.
• Production deployments should be traceable by release tag and deployment record.

8) Governance Summary

This setup enforces controlled upward promotion (feature/bugfix -> Develop -> Staging -> main), allows emergency hotfix routing, and combines:

• structural branch protections,
• approval/workflow controls,
• automated PR validation,
• and auditable tagged production release/rollback execution.