Skip to main content

Release One-Page Flow + Checklist

Use this page during every release. It is designed for fast execution by humans under time pressure.

1) Flow (Simple View)​

flowchart TD
    A[Feature work in dev] --> B[Release candidate tested in staging]
    B --> C[Merge approved candidate to main]
    C --> D[Run create-release script]
    D --> E[Push tag vX.Y.Z]
    E --> F[Release workflow creates changelog + GitHub Release]
    C --> G[CI on main completes successfully]
    G --> H[Deploy Production workflow]
    H --> I[Manual approval in GitHub Environment]
    I --> J[Build + push API/Web images]
    J --> K[Deploy to Coolify]
    K --> L[Health + version verification]

2) Human Steps​

  1. Merge approved release PR to main.
  2. Immediately tag that exact commit:
git checkout main
git pull origin main
./scripts/create-release.sh 1.2.3
  1. Watch these GitHub workflows:
  • CI
  • Deploy to Production (manual approval required)
  • Release
  1. Approve production deployment when ready.
  2. Verify production:
  • https://api.almafrica.com/health
  • https://api.almafrica.com/api/version
  • https://app.almafrica.com

3) Go/No-Go Checklist​

Before Merge to main​

  • Staging validation completed for critical user flows
  • Known issues documented and accepted
  • Rollback impact reviewed (especially DB migrations)

Before Tagging​

  • You are on main
  • Working tree is clean
  • Local main is up to date with origin/main
  • Correct semantic version chosen (X.Y.Z or X.Y.Z-rc.1)

During Deploy​

  • CI finished successfully on main
  • Production approval performed by authorized reviewer
  • Coolify deployment calls returned success

After Deploy​

  • API health endpoint returns 200
  • Web app responds normally
  • /api/version commit SHA matches expected commit
  • Smoke test: login + one critical business flow

4) If Something Goes Wrong​

  1. Stop further approvals/releases.
  2. Decide: roll forward (preferred) or rollback.
  3. For DB rollback steps, use:
  • docs/runbooks/database-rollback.md
  1. For staging data process, use:
  • docs/runbooks/staging-data-copy.md

5) Important Current Limitations​

  • Production deploy is triggered by CI on main, not directly by tag push.
  • If tag is late, deployment can use prod-<sha> instead of vX.Y.Z.
  • Pre-release tags (-beta, -rc) are currently not hard-blocked from production path.
  • Mobile store release process is separate from this flow.

6) Team Roles (Quick)​

  • Developer: prepares candidate, validates changes, runs tag script.
  • Reviewer/Lead: approves merge and production deployment.
  • Ops/On-call: monitors health and drives rollback if needed.