diff --git a/docs/CICD_MULTI_STAGE_BUILD.md b/docs/CICD_MULTI_STAGE_BUILD.md index 2257f48..b1c6db5 100644 --- a/docs/CICD_MULTI_STAGE_BUILD.md +++ b/docs/CICD_MULTI_STAGE_BUILD.md @@ -14,8 +14,9 @@ Current behavior to keep in mind: - Dependency audits run in one informational lane; frontend and backend audits always execute and are non-blocking. - Release and tester images are built in two merged producer jobs. - Deployable backend/frontend runtime images are first published as staging artifacts. -- A dedicated promotion lane publishes release image tags only after integration and E2E lanes succeed. -- Release promotion uses semver tags with a short commit SHA build suffix. +- A dedicated promotion lane publishes release image tags only after integration and E2E lanes succeed, and only for automated `push` runs on `main`. +- If a qualifying `main` commit is untagged, CI auto-creates the next patch tag starting from a `v0.0.0` baseline. +- Release promotion publishes release-line tags (`v..0`) plus patch/build tags (`v..`, `v..-<7-char-short-sha>`). - Registry operations include auth-realm host pinning and bounded retry logic for login/pull/push in critical lanes. - Runtime integration checks consume tag and digest outputs and verify they resolve to the same immutable artifact before assertions. diff --git a/docs/CICD_SUCCESS_SUMMARY.md b/docs/CICD_SUCCESS_SUMMARY.md index c01a56c..cfcedac 100644 --- a/docs/CICD_SUCCESS_SUMMARY.md +++ b/docs/CICD_SUCCESS_SUMMARY.md @@ -75,16 +75,18 @@ - `deployable-backend-staging` - `deployable-frontend-staging` - Runtime validation (`Runtime Black-Box Integration Tests` and `End-to-End Tests`) must pass before release tagging. -- `Promote Release Images` retags validated staging artifacts to release repositories: +- `Promote Release Images` retags validated staging artifacts to release repositories, but only on automated `push` runs to `main`: - `deployable-backend` - `deployable-frontend` - Published release tags: - `latest` - - `` - - `-<7-char-short-sha>` + - `v..0` + - `v..` + - `v..-<7-char-short-sha>` - Version selection rule: - - If HEAD has a semver git tag (`vX.Y.Z`), use it. - - Otherwise, auto-increment patch from the latest semver baseline for that major/minor line. + - If the qualifying `main` commit already has a semver git tag (`vX.Y.Z`), use it. + - Otherwise, auto-create and use the next patch tag from the latest semver tag in the repository. + - If no prior semver tag exists, bootstrap from `v0.0.0` and create `v0.0.1`. - Dependency audits are informational: frontend and backend audit steps both run and do not fail the full workflow. ### **Working Component Integration** diff --git a/docs/CICD_TROUBLESHOOTING_GUIDE.md b/docs/CICD_TROUBLESHOOTING_GUIDE.md index 6a850e5..b6b3ae1 100644 --- a/docs/CICD_TROUBLESHOOTING_GUIDE.md +++ b/docs/CICD_TROUBLESHOOTING_GUIDE.md @@ -125,8 +125,9 @@ staging images exist but deployable-backend/deployable-frontend tags not updated **Fast check**: 1. Confirm `Runtime Black-Box Integration Tests` and `End-to-End Tests` succeeded. -2. Check `Promote Release Images` logs for registry login, pull/tag/push failures. -3. Verify staging refs (`deployable-backend-staging`, `deployable-frontend-staging`) were emitted by `Build Release Images`. +2. Confirm the workflow run was an automated `push` on `main`; promotion is skipped for PR validation and other non-main events. +3. Check `Promote Release Images` logs for registry login, tag creation, pull/tag/push failures. +4. Verify staging refs (`deployable-backend-staging`, `deployable-frontend-staging`) were emitted by `Build Release Images`. **Fix**: @@ -142,13 +143,15 @@ release_version differs from expected manual guess **Cause**: promotion versioning follows workflow rules: -1. If HEAD commit has semver tag `vX.Y.Z`, use that exact version. -2. Otherwise, find latest semver baseline and auto-increment patch. -3. Also publish `-<7-char-short-sha>`. +1. Promotion only runs for automated `push` events on `main`. +2. If the `main` commit already has semver tag `vX.Y.Z`, use that exact patch tag. +3. Otherwise, find the latest semver tag in the repository and auto-create the next patch tag. +4. If no semver tag exists yet, bootstrap from `v0.0.0` and create `v0.0.1`. +5. Also publish `vX.Y.0` and `vX.Y.Z-<7-char-short-sha>`. **Fix**: -If you need an exact release version, tag the commit with semver before running promotion. +If you need an exact patch version, tag the `main` commit with semver before promotion runs; otherwise let CI assign the next patch automatically. ## Performance Optimizations diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 243ba15..30ff2e8 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -415,7 +415,7 @@ The pipeline is intentionally staged so expensive image jobs run only after sour 4. Runtime validation lanes: `Runtime Black-Box Integration Tests` and `End-to-End Tests` validate staged runtime artifacts. 5. Promotion lane: - `Promote Release Images` runs only when HEAD has a semver git tag and retags validated staging artifacts to release repos (`deployable-backend`, `deployable-frontend`) with `latest`, `..0`, ``, and `-<7-char-short-sha>` tags. + `Promote Release Images` runs only for automated `push` events on `main`. It retags validated staging artifacts to release repos (`deployable-backend`, `deployable-frontend`) with `latest`, `v..0`, `v..`, and `v..-<7-char-short-sha>` tags. If the `main` commit is untagged, CI creates the next patch tag automatically; if no prior semver tag exists, the bootstrap baseline is `v0.0.0`. 6. Postmortem lanes: targeted postmortem jobs run when key lanes fail to capture diagnostics even when primary jobs fail early. @@ -426,7 +426,7 @@ Current workflow behavior includes: - registry auth realm host pinning from `WWW-Authenticate` challenge when registry tokens are issued from a different host - bounded retry logic for docker login/pull/push operations in image lanes - digest/tag contract checks for deployable image references before runtime black-box tests -- release-note summary generation in the promotion lane (commit bullets since previous `..0` release tag) +- release-note summary generation in the promotion lane (commit bullets since the previous release tag, or from the `v0.0.0` bootstrap baseline on first release) - context hydration for image-build lanes by copying `/workspace` from the published CICD image - runner split between `ubuntu-act` and `ubuntu-act-8gb` based on lane resource requirements