Compare commits
5 Commits
todo/mvp0-
...
mvp0-compl
| Author | SHA1 | Date | |
|---|---|---|---|
|
37fabad1f8
|
|||
|
637dfd2651
|
|||
|
f9f2b4eb15
|
|||
|
ccac669454
|
|||
|
af52b8581f
|
45
.gitea/scripts/extract-release-notes.sh
Normal file
45
.gitea/scripts/extract-release-notes.sh
Normal file
@@ -0,0 +1,45 @@
|
|||||||
|
#!/usr/bin/env sh
|
||||||
|
set -eu
|
||||||
|
|
||||||
|
tag="${1:-}"
|
||||||
|
|
||||||
|
if [ -z "$tag" ]; then
|
||||||
|
echo "Missing release tag argument (expected vX.Y.Z)."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [ ! -f CHANGELOG.md ]; then
|
||||||
|
echo "CHANGELOG.md not found."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
version="${tag#v}"
|
||||||
|
|
||||||
|
awk -v version="$version" '
|
||||||
|
BEGIN {
|
||||||
|
in_section = 0
|
||||||
|
started = 0
|
||||||
|
}
|
||||||
|
/^## / {
|
||||||
|
if (in_section == 1) {
|
||||||
|
exit
|
||||||
|
}
|
||||||
|
|
||||||
|
if (index($0, version) > 0) {
|
||||||
|
in_section = 1
|
||||||
|
started = 1
|
||||||
|
print $0
|
||||||
|
next
|
||||||
|
}
|
||||||
|
}
|
||||||
|
{
|
||||||
|
if (in_section == 1) {
|
||||||
|
print $0
|
||||||
|
}
|
||||||
|
}
|
||||||
|
END {
|
||||||
|
if (started == 0) {
|
||||||
|
exit 2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
' CHANGELOG.md
|
||||||
80
.gitea/scripts/publish-gitea-release.mjs
Normal file
80
.gitea/scripts/publish-gitea-release.mjs
Normal file
@@ -0,0 +1,80 @@
|
|||||||
|
import { readFileSync } from "node:fs"
|
||||||
|
|
||||||
|
const tag = process.env.RELEASE_TAG?.trim()
|
||||||
|
const releaseName = process.env.RELEASE_NAME?.trim() || tag
|
||||||
|
const bodyFile = process.env.RELEASE_BODY_FILE?.trim() || ".gitea-release-notes.md"
|
||||||
|
const serverUrl = process.env.GITHUB_SERVER_URL?.trim()
|
||||||
|
const repository = process.env.GITHUB_REPOSITORY?.trim()
|
||||||
|
const token = process.env.GITEA_RELEASE_TOKEN?.trim()
|
||||||
|
|
||||||
|
if (!tag) {
|
||||||
|
throw new Error("RELEASE_TAG is required")
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!serverUrl || !repository) {
|
||||||
|
throw new Error("GITHUB_SERVER_URL and GITHUB_REPOSITORY are required")
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!token) {
|
||||||
|
throw new Error("GITEA_RELEASE_TOKEN is required")
|
||||||
|
}
|
||||||
|
|
||||||
|
const body = readFileSync(bodyFile, "utf8")
|
||||||
|
const baseApi = `${serverUrl.replace(/\/$/, "")}/api/v1/repos/${repository}`
|
||||||
|
|
||||||
|
async function request(path, options = {}) {
|
||||||
|
const response = await fetch(`${baseApi}${path}`, {
|
||||||
|
...options,
|
||||||
|
headers: {
|
||||||
|
"content-type": "application/json",
|
||||||
|
authorization: `token ${token}`,
|
||||||
|
...(options.headers ?? {}),
|
||||||
|
},
|
||||||
|
})
|
||||||
|
|
||||||
|
return response
|
||||||
|
}
|
||||||
|
|
||||||
|
const payload = {
|
||||||
|
tag_name: tag,
|
||||||
|
target_commitish: "main",
|
||||||
|
name: releaseName,
|
||||||
|
body,
|
||||||
|
draft: false,
|
||||||
|
prerelease: false,
|
||||||
|
}
|
||||||
|
|
||||||
|
const existingResponse = await request(`/releases/tags/${encodeURIComponent(tag)}`)
|
||||||
|
|
||||||
|
if (existingResponse.ok) {
|
||||||
|
const existing = await existingResponse.json()
|
||||||
|
const updateResponse = await request(`/releases/${existing.id}`, {
|
||||||
|
method: "PATCH",
|
||||||
|
body: JSON.stringify({
|
||||||
|
...payload,
|
||||||
|
target_commitish: existing.target_commitish ?? payload.target_commitish,
|
||||||
|
}),
|
||||||
|
})
|
||||||
|
|
||||||
|
if (!updateResponse.ok) {
|
||||||
|
const message = await updateResponse.text()
|
||||||
|
throw new Error(`Failed to update release: ${updateResponse.status} ${message}`)
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log(`Updated release for tag ${tag}`)
|
||||||
|
} else if (existingResponse.status === 404) {
|
||||||
|
const createResponse = await request("/releases", {
|
||||||
|
method: "POST",
|
||||||
|
body: JSON.stringify(payload),
|
||||||
|
})
|
||||||
|
|
||||||
|
if (!createResponse.ok) {
|
||||||
|
const message = await createResponse.text()
|
||||||
|
throw new Error(`Failed to create release: ${createResponse.status} ${message}`)
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log(`Created release for tag ${tag}`)
|
||||||
|
} else {
|
||||||
|
const message = await existingResponse.text()
|
||||||
|
throw new Error(`Failed to query existing release: ${existingResponse.status} ${message}`)
|
||||||
|
}
|
||||||
@@ -84,6 +84,12 @@ jobs:
|
|||||||
- name: Install dependencies
|
- name: Install dependencies
|
||||||
run: bun install --frozen-lockfile
|
run: bun install --frozen-lockfile
|
||||||
|
|
||||||
|
- name: Resolve build metadata
|
||||||
|
run: |
|
||||||
|
version=$(bun -e 'const pkg = JSON.parse(await Bun.file("package.json").text()); console.log(pkg.version)')
|
||||||
|
echo "NEXT_PUBLIC_APP_VERSION=$version" >> "$GITHUB_ENV"
|
||||||
|
echo "NEXT_PUBLIC_GIT_SHA=${GITHUB_SHA}" >> "$GITHUB_ENV"
|
||||||
|
|
||||||
- name: Install Playwright browser deps
|
- name: Install Playwright browser deps
|
||||||
run: bunx playwright install --with-deps chromium
|
run: bunx playwright install --with-deps chromium
|
||||||
|
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ on:
|
|||||||
inputs:
|
inputs:
|
||||||
release_tag:
|
release_tag:
|
||||||
description: "Release tag in vX.Y.Z format"
|
description: "Release tag in vX.Y.Z format"
|
||||||
required: true
|
required: false
|
||||||
rollback_image_tag:
|
rollback_image_tag:
|
||||||
description: "Optional rollback image tag"
|
description: "Optional rollback image tag"
|
||||||
required: false
|
required: false
|
||||||
@@ -21,6 +21,7 @@ env:
|
|||||||
jobs:
|
jobs:
|
||||||
release:
|
release:
|
||||||
name: Build Push Changelog
|
name: Build Push Changelog
|
||||||
|
if: github.event_name == 'push' || github.event.inputs.rollback_image_tag == ''
|
||||||
runs-on: node22-bun
|
runs-on: node22-bun
|
||||||
steps:
|
steps:
|
||||||
- name: Checkout
|
- name: Checkout
|
||||||
@@ -38,6 +39,10 @@ jobs:
|
|||||||
id: tag
|
id: tag
|
||||||
run: |
|
run: |
|
||||||
if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
|
if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
|
||||||
|
if [ -z "${{ github.event.inputs.release_tag }}" ]; then
|
||||||
|
echo "release_tag input is required when publishing a release manually."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
echo "value=${{ github.event.inputs.release_tag }}" >> "$GITHUB_OUTPUT"
|
echo "value=${{ github.event.inputs.release_tag }}" >> "$GITHUB_OUTPUT"
|
||||||
else
|
else
|
||||||
echo "value=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
|
echo "value=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
|
||||||
@@ -49,6 +54,13 @@ jobs:
|
|||||||
- name: Generate changelog
|
- name: Generate changelog
|
||||||
run: bun run changelog:release
|
run: bun run changelog:release
|
||||||
|
|
||||||
|
- name: Build release notes payload
|
||||||
|
run: |
|
||||||
|
if ! sh .gitea/scripts/extract-release-notes.sh "${{ steps.tag.outputs.value }}" > .gitea-release-notes.md; then
|
||||||
|
echo "Could not isolate section for tag ${{ steps.tag.outputs.value }}. Falling back to full CHANGELOG.md."
|
||||||
|
cp CHANGELOG.md .gitea-release-notes.md
|
||||||
|
fi
|
||||||
|
|
||||||
- name: Login to image registry
|
- name: Login to image registry
|
||||||
run: |
|
run: |
|
||||||
echo "${{ secrets.CMS_IMAGE_REGISTRY_PASSWORD }}" | docker login "${{ env.REGISTRY }}" -u "${{ secrets.CMS_IMAGE_REGISTRY_USER }}" --password-stdin
|
echo "${{ secrets.CMS_IMAGE_REGISTRY_PASSWORD }}" | docker login "${{ env.REGISTRY }}" -u "${{ secrets.CMS_IMAGE_REGISTRY_USER }}" --password-stdin
|
||||||
@@ -65,18 +77,27 @@ jobs:
|
|||||||
docker build -f apps/admin/Dockerfile -t "$image" .
|
docker build -f apps/admin/Dockerfile -t "$image" .
|
||||||
docker push "$image"
|
docker push "$image"
|
||||||
|
|
||||||
- name: Release notes placeholder
|
- name: Publish release notes to Gitea
|
||||||
run: |
|
env:
|
||||||
echo "Release tag: ${{ steps.tag.outputs.value }}"
|
RELEASE_TAG: ${{ steps.tag.outputs.value }}
|
||||||
echo "TODO: publish CHANGELOG.md content to release notes in Gitea."
|
RELEASE_NAME: ${{ steps.tag.outputs.value }}
|
||||||
|
RELEASE_BODY_FILE: ".gitea-release-notes.md"
|
||||||
|
GITEA_RELEASE_TOKEN: ${{ secrets.GITEA_RELEASE_TOKEN }}
|
||||||
|
run: bun .gitea/scripts/publish-gitea-release.mjs
|
||||||
|
|
||||||
rollback:
|
rollback:
|
||||||
name: Rollback (Manual)
|
name: Rollback Production (Manual)
|
||||||
if: github.event_name == 'workflow_dispatch' && github.event.inputs.rollback_image_tag != ''
|
if: github.event_name == 'workflow_dispatch' && github.event.inputs.rollback_image_tag != ''
|
||||||
runs-on: ubuntu-latest
|
runs-on: node22-bun
|
||||||
needs: release
|
|
||||||
steps:
|
steps:
|
||||||
- name: Rollback placeholder
|
- name: Setup SSH
|
||||||
run: |
|
run: |
|
||||||
echo "Rollback to image tag: ${{ github.event.inputs.rollback_image_tag }}"
|
mkdir -p ~/.ssh
|
||||||
echo "TODO: apply compose update with rollback image tags on production host."
|
echo "${{ secrets.CMS_DEPLOY_KEY }}" > ~/.ssh/id_rsa
|
||||||
|
chmod 600 ~/.ssh/id_rsa
|
||||||
|
ssh-keyscan -H "${{ secrets.CMS_PRODUCTION_HOST }}" >> ~/.ssh/known_hosts
|
||||||
|
|
||||||
|
- name: Apply rollback image tag on production
|
||||||
|
run: |
|
||||||
|
ssh "${{ secrets.CMS_PRODUCTION_USER }}@${{ secrets.CMS_PRODUCTION_HOST }}" \
|
||||||
|
"cd ${{ secrets.CMS_REMOTE_DEPLOY_PATH }} && CMS_IMAGE_TAG=${{ github.event.inputs.rollback_image_tag }} docker compose -f docker-compose.production.yml pull && CMS_IMAGE_TAG=${{ github.event.inputs.rollback_image_tag }} docker compose -f docker-compose.production.yml up -d"
|
||||||
|
|||||||
17
TODO.md
17
TODO.md
@@ -101,18 +101,18 @@ This file is the single source of truth for roadmap and delivery progress.
|
|||||||
- [x] [P1] Source of truth for version (`package.json` root) and release tagging rules (`vX.Y.Z`)
|
- [x] [P1] Source of truth for version (`package.json` root) and release tagging rules (`vX.Y.Z`)
|
||||||
- [x] [P1] Build metadata policy for git hash (`+sha.<short>`) in app runtime footer
|
- [x] [P1] Build metadata policy for git hash (`+sha.<short>`) in app runtime footer
|
||||||
- [x] [P1] App footer implementation plan for version + commit hash (admin + web)
|
- [x] [P1] App footer implementation plan for version + commit hash (admin + web)
|
||||||
- [~] [P2] Automated version injection in CI (stamping build from tag + commit hash)
|
- [x] [P2] Automated version injection in CI (stamping build from tag + commit hash)
|
||||||
- [ ] [P2] Validation tests for displayed version/hash consistency per deployment
|
- [x] [P2] Validation tests for displayed version/hash consistency per deployment
|
||||||
- [x] [P1] Release tagging and changelog publication policy in CI
|
- [x] [P1] Release tagging and changelog publication policy in CI
|
||||||
|
|
||||||
### MVP0 Close-Out Checklist
|
### MVP0 Close-Out Checklist
|
||||||
|
|
||||||
- [ ] [P1] Verify and document protected branch rules in Gitea (`main`, `staging`)
|
- [~] [P1] Verify and document protected branch rules in Gitea (`main`, `staging`)
|
||||||
- [ ] [P1] Run first staging deployment against a real host with deploy workflow and document result
|
- [~] [P1] Run first staging deployment against a real host with deploy workflow and document result
|
||||||
- [ ] [P1] Replace release workflow placeholders with real release-notes and rollback execution steps
|
- [x] [P1] Replace release workflow placeholders with real release-notes and rollback execution steps
|
||||||
- [x] [P1] Expose runtime version + short git hash in admin and public app footer
|
- [x] [P1] Expose runtime version + short git hash in admin and public app footer
|
||||||
- [ ] [P2] Add CI build stamping for version/hash values consumed by app footers
|
- [x] [P2] Add CI build stamping for version/hash values consumed by app footers
|
||||||
- [ ] [P2] Add automated tests validating displayed version/hash format and consistency
|
- [x] [P2] Add automated tests validating displayed version/hash format and consistency
|
||||||
|
|
||||||
## MVP 1: Core CMS Business Features
|
## MVP 1: Core CMS Business Features
|
||||||
|
|
||||||
@@ -218,6 +218,9 @@ This file is the single source of truth for roadmap and delivery progress.
|
|||||||
- [2026-02-10] i18n conventions are now documented as an engineering standard (`docs/product-engineering/i18n-conventions.md`).
|
- [2026-02-10] i18n conventions are now documented as an engineering standard (`docs/product-engineering/i18n-conventions.md`).
|
||||||
- [2026-02-10] Docs now include a domain glossary, public API glossary, and ADR baseline with initial accepted decision (`ADR 0001`).
|
- [2026-02-10] Docs now include a domain glossary, public API glossary, and ADR baseline with initial accepted decision (`ADR 0001`).
|
||||||
- [2026-02-10] Delivery and release governance now include branch/PR policy checks, deploy/release workflows, and explicit versioning policy (`VERSIONING.md`).
|
- [2026-02-10] Delivery and release governance now include branch/PR policy checks, deploy/release workflows, and explicit versioning policy (`VERSIONING.md`).
|
||||||
|
- [2026-02-11] Release workflow now publishes changelog-derived notes to Gitea releases and supports executable production rollback via SSH + compose tag switch.
|
||||||
|
- [2026-02-11] Branch protection verification checklist is now documented; final UI-level verification remains environment-specific.
|
||||||
|
- [2026-02-11] Added a staging deployment execution checklist and deployment-record template to capture first real-host rollout evidence.
|
||||||
|
|
||||||
## How We Use This File
|
## How We Use This File
|
||||||
|
|
||||||
|
|||||||
29
apps/admin/src/lib/build-info.test.ts
Normal file
29
apps/admin/src/lib/build-info.test.ts
Normal file
@@ -0,0 +1,29 @@
|
|||||||
|
import { afterEach, describe, expect, it, vi } from "vitest"
|
||||||
|
|
||||||
|
import { getBuildInfo } from "./build-info"
|
||||||
|
|
||||||
|
afterEach(() => {
|
||||||
|
vi.unstubAllEnvs()
|
||||||
|
})
|
||||||
|
|
||||||
|
describe("getBuildInfo (admin)", () => {
|
||||||
|
it("returns fallback values when env is missing", () => {
|
||||||
|
vi.stubEnv("NEXT_PUBLIC_APP_VERSION", "")
|
||||||
|
vi.stubEnv("NEXT_PUBLIC_GIT_SHA", "")
|
||||||
|
|
||||||
|
expect(getBuildInfo()).toEqual({
|
||||||
|
version: "0.0.1-dev",
|
||||||
|
sha: "local",
|
||||||
|
})
|
||||||
|
})
|
||||||
|
|
||||||
|
it("uses env values and truncates git sha", () => {
|
||||||
|
vi.stubEnv("NEXT_PUBLIC_APP_VERSION", "0.2.0")
|
||||||
|
vi.stubEnv("NEXT_PUBLIC_GIT_SHA", "abcdef123456")
|
||||||
|
|
||||||
|
expect(getBuildInfo()).toEqual({
|
||||||
|
version: "0.2.0",
|
||||||
|
sha: "abcdef1",
|
||||||
|
})
|
||||||
|
})
|
||||||
|
})
|
||||||
29
apps/web/src/lib/build-info.test.ts
Normal file
29
apps/web/src/lib/build-info.test.ts
Normal file
@@ -0,0 +1,29 @@
|
|||||||
|
import { afterEach, describe, expect, it, vi } from "vitest"
|
||||||
|
|
||||||
|
import { getBuildInfo } from "./build-info"
|
||||||
|
|
||||||
|
afterEach(() => {
|
||||||
|
vi.unstubAllEnvs()
|
||||||
|
})
|
||||||
|
|
||||||
|
describe("getBuildInfo (web)", () => {
|
||||||
|
it("returns fallback values when env is missing", () => {
|
||||||
|
vi.stubEnv("NEXT_PUBLIC_APP_VERSION", "")
|
||||||
|
vi.stubEnv("NEXT_PUBLIC_GIT_SHA", "")
|
||||||
|
|
||||||
|
expect(getBuildInfo()).toEqual({
|
||||||
|
version: "0.0.1-dev",
|
||||||
|
sha: "local",
|
||||||
|
})
|
||||||
|
})
|
||||||
|
|
||||||
|
it("uses env values and truncates git sha", () => {
|
||||||
|
vi.stubEnv("NEXT_PUBLIC_APP_VERSION", "0.2.0")
|
||||||
|
vi.stubEnv("NEXT_PUBLIC_GIT_SHA", "123456789abc")
|
||||||
|
|
||||||
|
expect(getBuildInfo()).toEqual({
|
||||||
|
version: "0.2.0",
|
||||||
|
sha: "1234567",
|
||||||
|
})
|
||||||
|
})
|
||||||
|
})
|
||||||
16
bun.lock
16
bun.lock
@@ -17,7 +17,7 @@
|
|||||||
"conventional-changelog-cli": "5.0.0",
|
"conventional-changelog-cli": "5.0.0",
|
||||||
"jsdom": "28.0.0",
|
"jsdom": "28.0.0",
|
||||||
"msw": "2.12.9",
|
"msw": "2.12.9",
|
||||||
"turbo": "2.8.3",
|
"turbo": "^2.8.6",
|
||||||
"typescript": "5.9.3",
|
"typescript": "5.9.3",
|
||||||
"vite-tsconfig-paths": "6.1.0",
|
"vite-tsconfig-paths": "6.1.0",
|
||||||
"vitepress": "1.6.4",
|
"vitepress": "1.6.4",
|
||||||
@@ -1451,19 +1451,19 @@
|
|||||||
|
|
||||||
"tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
|
"tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
|
||||||
|
|
||||||
"turbo": ["turbo@2.8.3", "", { "optionalDependencies": { "turbo-darwin-64": "2.8.3", "turbo-darwin-arm64": "2.8.3", "turbo-linux-64": "2.8.3", "turbo-linux-arm64": "2.8.3", "turbo-windows-64": "2.8.3", "turbo-windows-arm64": "2.8.3" }, "bin": { "turbo": "bin/turbo" } }, "sha512-8Osxz5Tu/Dw2kb31EAY+nhq/YZ3wzmQSmYa1nIArqxgCAldxv9TPlrAiaBUDVnKA4aiPn0OFBD1ACcpc5VFOAQ=="],
|
"turbo": ["turbo@2.8.6", "", { "optionalDependencies": { "turbo-darwin-64": "2.8.6", "turbo-darwin-arm64": "2.8.6", "turbo-linux-64": "2.8.6", "turbo-linux-arm64": "2.8.6", "turbo-windows-64": "2.8.6", "turbo-windows-arm64": "2.8.6" }, "bin": { "turbo": "bin/turbo" } }, "sha512-QMj1SQwUYehc+xJ9SxXn56UO43hfKN64/NFetVW1BwzysRqn+q0FSgrmk+IbJ+djfd8j8zXGKGeqsnUcXwQSUQ=="],
|
||||||
|
|
||||||
"turbo-darwin-64": ["turbo-darwin-64@2.8.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-4kXRLfcygLOeNcP6JquqRLmGB/ATjjfehiojL2dJkL7GFm3SPSXbq7oNj8UbD8XriYQ5hPaSuz59iF1ijPHkTw=="],
|
"turbo-darwin-64": ["turbo-darwin-64@2.8.6", "", { "os": "darwin", "cpu": "x64" }, "sha512-6QeZ/aLZizekiI6tKZN0IGP1a1WYZ9c/qDKPa0rSmj2X0O0Iw/ES4rKZV40S5n8SUJdiU01EFLygHJ2oWaYKXg=="],
|
||||||
|
|
||||||
"turbo-darwin-arm64": ["turbo-darwin-arm64@2.8.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-xF7uCeC0UY0Hrv/tqax0BMbFlVP1J/aRyeGQPZT4NjvIPj8gSPDgFhfkfz06DhUwDg5NgMo04uiSkAWE8WB/QQ=="],
|
"turbo-darwin-arm64": ["turbo-darwin-arm64@2.8.6", "", { "os": "darwin", "cpu": "arm64" }, "sha512-RS4Z902vB93cQD3PJS/1IMmS0HefrB5ZXuw4ECOrxhOGz5jJVmYFJ6weDzedjoTDeYHHXGo1NoiCSHg69ngWKA=="],
|
||||||
|
|
||||||
"turbo-linux-64": ["turbo-linux-64@2.8.3", "", { "os": "linux", "cpu": "x64" }, "sha512-vxMDXwaOjweW/4etY7BxrXCSkvtwh0PbwVafyfT1Ww659SedUxd5rM3V2ZCmbwG8NiCfY7d6VtxyHx3Wh1GoZA=="],
|
"turbo-linux-64": ["turbo-linux-64@2.8.6", "", { "os": "linux", "cpu": "x64" }, "sha512-hCWDnDepYbrSJdByuryKFoHAGFkvgBYXr6qdaGsYhX1Wgq8isqXCQBKOo99Y/9tXDwKGEeQ7xnkdFvSL7AQ4iQ=="],
|
||||||
|
|
||||||
"turbo-linux-arm64": ["turbo-linux-arm64@2.8.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-mQX7uYBZFkuPLLlKaNe9IjR1JIef4YvY8f21xFocvttXvdPebnq3PK1Zjzl9A1zun2BEuWNUwQIL8lgvN9Pm3Q=="],
|
"turbo-linux-arm64": ["turbo-linux-arm64@2.8.6", "", { "os": "linux", "cpu": "arm64" }, "sha512-oS15aCYEpynG/l69xs/ZnQ0dnz0pHhfHg70Zf5J+j5Cam0/RA0MpcryjneN/9G0PmP8a/6ZxnL5nZahX+wOBPA=="],
|
||||||
|
|
||||||
"turbo-windows-64": ["turbo-windows-64@2.8.3", "", { "os": "win32", "cpu": "x64" }, "sha512-YLGEfppGxZj3VWcNOVa08h6ISsVKiG85aCAWosOKNUjb6yErWEuydv6/qImRJUI+tDLvDvW7BxopAkujRnWCrw=="],
|
"turbo-windows-64": ["turbo-windows-64@2.8.6", "", { "os": "win32", "cpu": "x64" }, "sha512-eqBxqJD7H/uk9V0QO10VgwY9J2BUXejsGuzChln72Yl+o8GZwsvhOekndRxccR90J8ZO+LKO24+3VzHFh4Cu/g=="],
|
||||||
|
|
||||||
"turbo-windows-arm64": ["turbo-windows-arm64@2.8.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-afTUGKBRmOJU1smQSBnFGcbq0iabAPwh1uXu2BVk7BREg30/1gMnJh9DFEQTah+UD3n3ru8V55J83RQNFfqoyw=="],
|
"turbo-windows-arm64": ["turbo-windows-arm64@2.8.6", "", { "os": "win32", "cpu": "arm64" }, "sha512-I3VEQyxIlNZ6XTg4fLKAkuhcwzIs/GD7Vs1yhelH2aUTjf08wprjBWknDqP7mjAHMpsosRrq4DtfSZEQm83Hxg=="],
|
||||||
|
|
||||||
"type-fest": ["type-fest@5.4.4", "", { "dependencies": { "tagged-tag": "^1.0.0" } }, "sha512-JnTrzGu+zPV3aXIUhnyWJj4z/wigMsdYajGLIYakqyOW1nPllzXEJee0QQbHj+CTIQtXGlAjuK0UY+2xTyjVAw=="],
|
"type-fest": ["type-fest@5.4.4", "", { "dependencies": { "tagged-tag": "^1.0.0" } }, "sha512-JnTrzGu+zPV3aXIUhnyWJj4z/wigMsdYajGLIYakqyOW1nPllzXEJee0QQbHj+CTIQtXGlAjuK0UY+2xTyjVAw=="],
|
||||||
|
|
||||||
|
|||||||
@@ -28,8 +28,14 @@ Policy:
|
|||||||
- Steps:
|
- Steps:
|
||||||
1. validate tag vs root `package.json` version
|
1. validate tag vs root `package.json` version
|
||||||
2. generate changelog
|
2. generate changelog
|
||||||
3. docker login
|
3. extract release notes from `CHANGELOG.md`
|
||||||
4. build and push `cms-web` and `cms-admin` images
|
4. docker login
|
||||||
|
5. build and push `cms-web` and `cms-admin` images
|
||||||
|
6. publish/update Gitea release notes through API
|
||||||
|
|
||||||
|
Additional required secret:
|
||||||
|
|
||||||
|
- `GITEA_RELEASE_TOKEN`
|
||||||
|
|
||||||
## Staging Deployment Automation
|
## Staging Deployment Automation
|
||||||
|
|
||||||
@@ -57,10 +63,10 @@ Promotion:
|
|||||||
|
|
||||||
Rollback:
|
Rollback:
|
||||||
|
|
||||||
- release workflow supports rollback placeholder by image tag
|
- release workflow supports manual production rollback by `rollback_image_tag`
|
||||||
- deploy workflow supports `rollback_tag` input
|
- deploy workflow supports `rollback_tag` input for environment-specific rollback
|
||||||
- recovery action:
|
- recovery action:
|
||||||
- rerun deploy with previous known-good tag
|
- rerun deploy/rollback with previous known-good tag
|
||||||
|
|
||||||
## Deployment Verification
|
## Deployment Verification
|
||||||
|
|
||||||
|
|||||||
@@ -23,6 +23,33 @@ Minimum policy:
|
|||||||
- required status checks
|
- required status checks
|
||||||
- at least one reviewer approval
|
- at least one reviewer approval
|
||||||
|
|
||||||
|
## Branch Protection Verification Checklist
|
||||||
|
|
||||||
|
Use this checklist in Gitea repository settings after applying policy:
|
||||||
|
|
||||||
|
1. `main` protection exists and direct push is disabled.
|
||||||
|
2. `staging` protection exists and direct push is disabled.
|
||||||
|
3. Required checks include:
|
||||||
|
- `Governance Checks`
|
||||||
|
- `Lint Typecheck Unit E2E`
|
||||||
|
4. Pull request approval is required.
|
||||||
|
5. Branch must be up to date before merge (recommended in protected branches).
|
||||||
|
|
||||||
|
API automation example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sh .gitea/scripts/configure-branch-protection.sh \
|
||||||
|
"$GITEA_URL" \
|
||||||
|
"$GITEA_OWNER" \
|
||||||
|
"$GITEA_REPO" \
|
||||||
|
"$GITEA_ADMIN_TOKEN"
|
||||||
|
```
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
|
||||||
|
- The script applies baseline protection for `main` and `staging`.
|
||||||
|
- Final verification is still required in the Gitea UI to confirm repository-specific policies.
|
||||||
|
|
||||||
## PR Gates
|
## PR Gates
|
||||||
|
|
||||||
Required checks are implemented in `.gitea/workflows/ci.yml`:
|
Required checks are implemented in `.gitea/workflows/ci.yml`:
|
||||||
|
|||||||
@@ -12,6 +12,7 @@ This section covers platform and implementation documentation for engineers and
|
|||||||
- [CRUD Examples](/product-engineering/crud-examples)
|
- [CRUD Examples](/product-engineering/crud-examples)
|
||||||
- [Domain Glossary](/product-engineering/domain-glossary)
|
- [Domain Glossary](/product-engineering/domain-glossary)
|
||||||
- [Environment Runbook](/product-engineering/environment-runbook)
|
- [Environment Runbook](/product-engineering/environment-runbook)
|
||||||
|
- [Staging Deployment Checklist](/product-engineering/staging-deployment-checklist)
|
||||||
- [Delivery Pipeline](/product-engineering/delivery-pipeline)
|
- [Delivery Pipeline](/product-engineering/delivery-pipeline)
|
||||||
- [Git Flow Governance](/product-engineering/git-flow-governance)
|
- [Git Flow Governance](/product-engineering/git-flow-governance)
|
||||||
- [Testing Strategy Baseline](/product-engineering/testing-strategy)
|
- [Testing Strategy Baseline](/product-engineering/testing-strategy)
|
||||||
|
|||||||
100
docs/product-engineering/staging-deployment-checklist.md
Normal file
100
docs/product-engineering/staging-deployment-checklist.md
Normal file
@@ -0,0 +1,100 @@
|
|||||||
|
# Staging Deployment Checklist
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Operational checklist for the first real staging deployment using `.gitea/workflows/deploy.yml`.
|
||||||
|
|
||||||
|
Use this once end-to-end, save the record, then mark MVP0 staging deployment as complete in `TODO.md`.
|
||||||
|
|
||||||
|
## Preconditions
|
||||||
|
|
||||||
|
- Docker host for staging is reachable via SSH.
|
||||||
|
- Gitea repo secrets are configured:
|
||||||
|
- `CMS_STAGING_HOST`
|
||||||
|
- `CMS_STAGING_USER`
|
||||||
|
- `CMS_DEPLOY_KEY`
|
||||||
|
- `CMS_REMOTE_DEPLOY_PATH`
|
||||||
|
- `CMS_IMAGE_REGISTRY`
|
||||||
|
- `CMS_IMAGE_NAMESPACE`
|
||||||
|
- `CMS_IMAGE_REGISTRY_USER`
|
||||||
|
- `CMS_IMAGE_REGISTRY_PASSWORD`
|
||||||
|
- Release image tag exists in registry (e.g. `v0.1.0`).
|
||||||
|
- Remote deploy path contains:
|
||||||
|
- `docker-compose.staging.yml`
|
||||||
|
- staging env file(s) needed by compose
|
||||||
|
|
||||||
|
## Step-by-Step Execution
|
||||||
|
|
||||||
|
1. Verify release images exist:
|
||||||
|
- `cms-web:<tag>`
|
||||||
|
- `cms-admin:<tag>`
|
||||||
|
2. In Gitea Actions, run `CMS Deploy` workflow.
|
||||||
|
3. Inputs:
|
||||||
|
- `environment=staging`
|
||||||
|
- `image_tag=<tag>`
|
||||||
|
- `rollback_tag=` (empty for normal deploy)
|
||||||
|
4. Confirm workflow success.
|
||||||
|
5. Validate staging endpoints:
|
||||||
|
- web base route
|
||||||
|
- admin login route
|
||||||
|
6. Run smoke checks on staging:
|
||||||
|
- auth login
|
||||||
|
- i18n route/switch baseline
|
||||||
|
- admin dashboard route access
|
||||||
|
7. If failure:
|
||||||
|
- rerun `CMS Deploy` with `rollback_tag=<previous-tag>`
|
||||||
|
- capture root cause and remediation notes
|
||||||
|
|
||||||
|
## Evidence To Capture
|
||||||
|
|
||||||
|
- Workflow run URL
|
||||||
|
- Deployed image tag
|
||||||
|
- Timestamp (UTC)
|
||||||
|
- Validation results (pass/fail)
|
||||||
|
- Rollback performed or not
|
||||||
|
|
||||||
|
## Deployment Record Template
|
||||||
|
|
||||||
|
Copy the block below into a new file under `docs/product-engineering/staging-deployments/`.
|
||||||
|
|
||||||
|
```md
|
||||||
|
# Staging Deployment Record - <YYYY-MM-DD>
|
||||||
|
|
||||||
|
- Date (UTC):
|
||||||
|
- Operator:
|
||||||
|
- Workflow run URL:
|
||||||
|
- Target environment: staging
|
||||||
|
- Image tag:
|
||||||
|
- Previous tag:
|
||||||
|
|
||||||
|
## Preconditions
|
||||||
|
|
||||||
|
- [ ] Secrets configured in Gitea
|
||||||
|
- [ ] Registry images available
|
||||||
|
- [ ] Remote compose path verified
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
1. Triggered `CMS Deploy` with `environment=staging`, `image_tag=<tag>`
|
||||||
|
2. Workflow status: <!-- pass/fail -->
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
- [ ] Web route check
|
||||||
|
- [ ] Admin login route check
|
||||||
|
- [ ] Auth smoke flow
|
||||||
|
- [ ] i18n smoke flow
|
||||||
|
- [ ] Admin dashboard access
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
- Performed: <!-- yes/no -->
|
||||||
|
- Rollback tag:
|
||||||
|
- Rollback workflow run URL:
|
||||||
|
|
||||||
|
## Outcome
|
||||||
|
|
||||||
|
- Result: <!-- success/failed -->
|
||||||
|
- Notes:
|
||||||
|
- Follow-up actions:
|
||||||
|
```
|
||||||
@@ -1,10 +1,13 @@
|
|||||||
import { expect, test } from "@playwright/test"
|
import { expect, test } from "@playwright/test"
|
||||||
|
|
||||||
|
const BUILD_INFO_PATTERN = /Build v\S+ \+sha\.[a-z0-9]{5,7}/i
|
||||||
|
|
||||||
test("smoke", async ({ page }, testInfo) => {
|
test("smoke", async ({ page }, testInfo) => {
|
||||||
await page.goto("/")
|
await page.goto("/")
|
||||||
|
|
||||||
if (testInfo.project.name === "web-chromium") {
|
if (testInfo.project.name === "web-chromium") {
|
||||||
await expect(page.getByRole("heading", { name: /your next\.js cms frontend/i })).toBeVisible()
|
await expect(page.getByRole("heading", { name: /your next\.js cms frontend/i })).toBeVisible()
|
||||||
|
await expect(page.getByText(BUILD_INFO_PATTERN)).toBeVisible()
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -12,6 +15,7 @@ test("smoke", async ({ page }, testInfo) => {
|
|||||||
|
|
||||||
if (await dashboardHeading.isVisible({ timeout: 2000 })) {
|
if (await dashboardHeading.isVisible({ timeout: 2000 })) {
|
||||||
await expect(dashboardHeading).toBeVisible()
|
await expect(dashboardHeading).toBeVisible()
|
||||||
|
await expect(page.getByText(BUILD_INFO_PATTERN)).toBeVisible()
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
10
package.json
10
package.json
@@ -44,22 +44,22 @@
|
|||||||
"docker:production:down": "docker compose -f docker-compose.production.yml down"
|
"docker:production:down": "docker compose -f docker-compose.production.yml down"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@playwright/test": "1.58.2",
|
"@biomejs/biome": "2.3.14",
|
||||||
"@commitlint/cli": "20.4.1",
|
"@commitlint/cli": "20.4.1",
|
||||||
"@commitlint/config-conventional": "20.4.1",
|
"@commitlint/config-conventional": "20.4.1",
|
||||||
|
"@playwright/test": "1.58.2",
|
||||||
"@testing-library/jest-dom": "6.9.1",
|
"@testing-library/jest-dom": "6.9.1",
|
||||||
"@testing-library/react": "16.3.2",
|
"@testing-library/react": "16.3.2",
|
||||||
"@testing-library/user-event": "14.6.1",
|
"@testing-library/user-event": "14.6.1",
|
||||||
"@vitejs/plugin-react": "5.1.3",
|
"@vitejs/plugin-react": "5.1.3",
|
||||||
"@vitest/coverage-istanbul": "4.0.18",
|
"@vitest/coverage-istanbul": "4.0.18",
|
||||||
"@biomejs/biome": "2.3.14",
|
"conventional-changelog-cli": "5.0.0",
|
||||||
"jsdom": "28.0.0",
|
"jsdom": "28.0.0",
|
||||||
"msw": "2.12.9",
|
"msw": "2.12.9",
|
||||||
"conventional-changelog-cli": "5.0.0",
|
"turbo": "^2.8.6",
|
||||||
"turbo": "2.8.3",
|
|
||||||
"typescript": "5.9.3",
|
"typescript": "5.9.3",
|
||||||
"vitepress": "1.6.4",
|
|
||||||
"vite-tsconfig-paths": "6.1.0",
|
"vite-tsconfig-paths": "6.1.0",
|
||||||
|
"vitepress": "1.6.4",
|
||||||
"vitest": "4.0.18"
|
"vitest": "4.0.18"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user