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)

```mermaid
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.