[bobdivx]

Problem

DevForge was stuck on version 4.1.3 because every Docker Images build on main overwrote the same bobdivx/devforge:4.1.3 tag. The updates page at /settings/updates/ compares semver from backend/versions.json (fetched from GitHub) vs the running backend/config/constants.php, so 4.1.3 vs 4.1.3 = no update detected.

Solution

This PR implements automatic version bumping in the CI pipeline with the correct job ordering to ensure Docker Hub and GitHub versions always match.

Critical Design: Why This Order?

❌ Broken flow (commit first):

bump+commit → build

If build fails, GitHub has 4.1.4 but Hub still has 4.1.3 → updates page lies about available version.

✅ Correct flow (commit after success):

prepare → build+push → commit-version (only if success)

Docker Hub gets 4.1.4 first, then GitHub is updated only after images are confirmed published.

Jobs Flow

1. prepare job: Calculate next version

   • Checkout triggering commit
   • Read current version from backend/config/constants.php (coolify.version)
   • Increment patch: 4.1.3 → 4.1.4
   • Output current and version for downstream jobs
   • Does NOT commit — version is only calculated

2. build job: Apply patch and build images (matrix)

   • Checkout triggering SHA (not hardcoded main — avoids race)
   • Apply version patch in workspace:
     • backend/config/constants.php (coolify.version)
     • backend/versions.json (devforge.version + coolify.v4.version)
   • Build all components: api, web, realtime, helper, proxy
   • Push to Docker Hub with tags:
     • bobdivx/devforge:latest (api)
     • bobdivx/devforge:X.Y.Z (api)
     • bobdivx/devforge:{component}-X.Y.Z
     • :sha-XXXXXXX tags for rollback
   • Mirror to GHCR

3. commit-version job: Update GitHub main (only after full build success)

   • if: success() — skipped if any build job failed
   • needs: [prepare, build] — waits for full matrix
   • Checkout github.ref_name with GITHUB_TOKEN
   • Apply same version patch
   • Commit: chore: bump version to X.Y.Z [skip version bump]
   • Push: git push origin HEAD:${{ github.ref_name }}
   • Idempotent: no-op if files already have target version

Bug Fixes in This PR

1. Fixed detached HEAD git push failure

   • Old: actions/checkout@v5 on push event checked out GITHUB_SHA detached
   • New: commit-version uses ref: ${{ github.ref_name }} + token: ${{ secrets.GITHUB_TOKEN }}

2. Fixed version mismatch when build fails

   • Old: bump+commit ran before build
   • New: commit runs only after successful build matrix

3. Fixed build skip when bump is skipped

   • Old: needs: bump-version + if: !contains skip blocked dependent jobs
   • New: No skip on prepare, build always runs
   • Note: GITHUB_TOKEN pushes don't retrigger workflows anyway

4. Fixed checkout racing to wrong commit

   • Old: ref: main hardcoded — could race with concurrent pushes
   • New: Checkout triggering SHA in build, github.ref_name in commit-version

5. Improved version extraction precision

   • Old: sed on first 'version' => could match wrong field
   • New: awk scoped to coolify array block, targets coolify.version only

How It Works After Merge

Push to main (code change)
  ↓
prepare: compute 4.1.3 → 4.1.4
  ↓
build: patch workspace to 4.1.4 → docker build → push Hub :4.1.4
  ↓
(If build succeeded)
  ↓
commit-version: patch GitHub main → commit → push
  ↓
versions.json on GitHub now shows 4.1.4
  ↓
Live instance at https://web.briseteia.me
  - Running: 4.1.3
  - Fetches versions.json: 4.1.4
  - /settings/updates/ shows "New version available"

Loop Prevention

Q: Why doesn't the version commit re-trigger infinitely?

A: GITHUB_TOKEN pushes do not trigger workflows (GitHub native behavior). Even if a PAT is used later, the [skip version bump] marker can be checked. The commit-version job also checks if files already have the target version (idempotent).

Manual Bumping

Script scripts/bump-devforge-version.sh is provided for local development:

./scripts/bump-devforge-version.sh [patch|minor|major]

Note: Manual bumps will trigger the CI workflow, which computes the next version. If you manually set 4.2.0, the workflow will build 4.2.0 then prepare 4.2.1 for the next build.

Testing Plan

After this PR merges to main:

1. First build: Will bump 4.1.3 → 4.1.4 and push to Hub
2. commit-version will update GitHub versions.json to 4.1.4
3. Live instance can then see the update at /settings/updates/
4. Subsequent builds: 4.1.4 → 4.1.5 → 4.1.6 (continuous auto-increment)
5. Failed builds: No version is committed to GitHub (prevents lying)

Files Changed

• .github/workflows/devforge-images.yml — Correct prepare → build → commit-version flow
• scripts/bump-devforge-version.sh — Manual bump helper with improved extraction
• docs/VERSIONING.md — Complete documentation with flow diagram and troubleshooting

Related

• Repo: https://github.com/bobdivx/devforge
• Live instance: https://web.briseteia.me
• Docker Hub: https://hub.docker.com/r/bobdivx/devforge
• Updates page: https://web.briseteia.me/settings/updates/

---

Important: This PR must be merged for the auto-versioning to begin. The first successful build after merge will create version 4.1.4.