Add Deployment Setup: manual Gitea Actions build/test/artifact pipeline

Co-authored-by: Junie <junie@jetbrains.com>
2026-07-20 01:40:46 +02:00
parent e299f1c745
commit 19b1101c1b
7 changed files with 213 additions and 12 deletions
@@ -0,0 +1,68 @@
+name: Build, Test and Package Release
+
+# Manually triggered pipeline (see aidlc-docs/features/react-frontend/operations/deployment/deployment-instructions.md):
+# - Run it yourself from Gitea Actions, picking the branch/ref to run against.
+# - Always runs the build/test/lint gate first.
+# - The "deploy" step currently only packages dist/ as a downloadable artifact
+#   (no automatic upload to a host yet). Typically run on a `release/*` branch
+#   once you've manually created it for a release.
+
+on:
+  workflow_dispatch: {}
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm run lint
+
+      - name: Unit tests
+        run: pnpm run test
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 30
+
+  deploy:
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      # Placeholder deploy step: for now this only re-publishes dist/ as a clearly
+      # named, ready-to-download artifact. Once the hosting/upload method (FTP/SFTP/
+      # other) is finalized, replace this step with the actual upload and this
+      # comment can be removed.
+      - name: Package release artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dist
+          path: dist/
+          retention-days: 30
@@ -5,7 +5,7 @@
 - **Feature Slug**: react-frontend
 - **Project Type**: Greenfield
 - **Start Date**: 2026-07-18T00:37:00Z
- **Current Stage**: CONSTRUCTION - Build and Test Complete, awaiting Operations decision
+- **Current Stage**: OPERATIONS - Deployment Setup Complete, awaiting approval
 - **Branch**: master

 ## Workspace State
@@ -33,6 +33,10 @@
 - **Include Operations Phase**: Yes
 - **Decided At**: Requirements Analysis

+### Deployment Setup
+- **Included**: Yes
+- **Method**: Manually-triggered Gitea Actions pipeline (build/test/lint gate + artifact packaging); actual host upload is manual for now, to be automated later
+
 ## Execution Plan Summary
 - **Total Stages**: 10 (2 skipped, 8 executed)
 - **Stages to Execute**: Functional Design, NFR Requirements, NFR Design, Code Generation, Build and Test, Deployment Setup, Monitoring Setup, Production Readiness Validation
@@ -57,12 +61,12 @@
 - [x] Build and Test (EXECUTE) - Completed 2026-07-19

 ### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup (EXECUTE)
+- [x] Deployment Setup (EXECUTE) - Completed 2026-07-19
 - [ ] Monitoring Setup (EXECUTE)
 - [ ] Production Readiness Validation (EXECUTE)

 ## Current Status
- **Lifecycle Phase**: CONSTRUCTION
- **Current Stage**: Build and Test Complete, awaiting approval
- **Next Stage**: Deployment Setup (Operations Phase)
+- **Lifecycle Phase**: OPERATIONS
+- **Current Stage**: Deployment Setup Complete, awaiting approval
+- **Next Stage**: Monitoring Setup (Operations Phase)
 - **Status**: Ready to proceed
@@ -251,3 +251,39 @@
 **Context**: Build and Test stage (CONSTRUCTION PHASE) executed; presenting completion message with Operations Phase decision (Include Operations Phase = Yes, decided at Requirements Analysis).

 ---
+
+## Build and Test - Approved / Deployment Setup Started
+
+**Timestamp**: 2026-07-19T22:50:00Z
+
+**User Input**: "Doorgaan naar volgende fase" (Continue to next phase)
+
+**AI Response**: "Build and Test stage approved. Started Deployment Setup (OPERATIONS PHASE): created a 7-question plan at operations/plans/deployment-setup-plan.md covering inclusion, method, environments, automation level, rollback strategy, target host, and secrets storage."
+
+**Context**: Build and Test stage complete and approved; moved to Deployment Setup stage.
+
+---
+
+## Deployment Setup - Answers Received and Artifacts Generated
+
+**Timestamp**: 2026-07-19T23:10:00Z
+
+**User Input**: "Q1:A (yes), Q2:A with Gitea Actions, Q3:C (dev/staging/production), Q4:A (fully automated), Q5:B (git tags/releases), Q6:D (host not yet finalized - mijnhostingpartner.nl, possibly combined with future backend/CMS), Q7:D (Gitea Actions Secrets)" (filled in directly in deployment-setup-plan.md)
+
+**AI Response**: "Method: CI/CD pipeline via Gitea Actions, deploying the static dist/ build to a traditional FTP/SFTP webhost. Proposed a branch/tag strategy (develop -> Development, staging -> Staging, v*.*.* tag on master -> Production) since it wasn't explicitly asked. Generated deployment-plan.md, deployment-instructions.md, rollback-plan.md under operations/deployment/, plus a working .gitea/workflows/deploy.yml pipeline (build/test/lint gate + 3 environment deploy jobs via FTP-Deploy-Action, secrets/variables for host/credentials/paths). Flagged the unresolved hosting/domain structure (Q6) as an open item requiring no workflow changes once resolved, only variable values."
+
+**Context**: Deployment Setup (OPERATIONS PHASE) - Step 6 artifacts generated; presenting completion message.
+
+---
+
+## Deployment Setup - Requested Changes: Simplified Pipeline
+
+**Timestamp**: 2026-07-19T23:15:00Z
+
+**User Input**: "ik zat niet helemaal na te denken. ik wil een pipeline die ik zelf kan aftrappen. Hierop zit een build en test CI. Bij een release wil ik een release-branch aanmaken. Op de release branch zit ook een handmatige deploy-stap. Voor nu zet die alleen de build uit de dist-map als artifact klaar. Mocht ik het later automatisch kunnen deployen dan pas ik dat verder aan. De staging deployment mag dus weg"
+
+**AI Response**: "Rewrote .gitea/workflows/deploy.yml to a single manually-triggered (workflow_dispatch) pipeline: build-and-test job (install/lint/test/build) followed by a deploy job that only re-publishes dist/ as a release-dist artifact (placeholder, no automatic host upload yet). Removed the development/staging/production auto-deploy jobs and the FTP-Deploy-Action usage. Updated deployment-plan.md, deployment-instructions.md, and rollback-plan.md to describe the manual release/* branch workflow, manual trigger, manual artifact upload, and manual rollback via re-running the pipeline against a previous branch."
+
+**Context**: Deployment Setup (OPERATIONS PHASE) - requested change addressed, re-presenting completion message.
+
+---
@@ -0,0 +1,36 @@
+# Deployment Instructions
+
+## Overview
+Deployment is currently a **manually-triggered Gitea Actions pipeline**: `.gitea/workflows/deploy.yml`. You start it yourself from the Gitea Actions UI; it runs the build/test/lint gate and then packages the `dist/` build as a downloadable artifact. There is no automatic upload to a host yet — you upload the artifact yourself for now.
+
+## Pipeline File
+`.gitea/workflows/deploy.yml` — triggered by `workflow_dispatch` only (no automatic trigger on push/tag). Two jobs:
+- `build-and-test` — install, lint, unit tests, build; uploads `dist/` as the `dist` artifact
+- `deploy` — downloads that artifact and republishes it as `release-dist` (placeholder for a future automatic upload step)
+
+## How to Prepare and Run a Release
+
+### 1. Create a release branch (manual, your own git flow)
+```bash
+git checkout master
+git pull
+git checkout -b release/1.0.0
+git push origin release/1.0.0
+```
+
+### 2. Trigger the pipeline manually
+1. In Gitea, open the repository's **Actions** tab.
+2. Select the **Build, Test and Package Release** workflow.
+3. Click **Run workflow**, choose the `release/1.0.0` branch (or whichever ref you want to build), and start it.
+
+### 3. Download and upload the artifact
+1. Once the run finishes successfully, open the run's summary page in Gitea Actions.
+2. Download the **release-dist** artifact (a zip of the `dist/` folder).
+3. Upload its contents to your host manually (e.g. via your FTP/SFTP client), using whatever hosting setup you finalize with mijnhostingpartner.nl.
+
+## Verifying a Deployment
+1. Confirm the Gitea Actions run completed successfully (`build-and-test` and `deploy` both green).
+2. After manually uploading the artifact contents, open the live site in a browser and confirm it loads correctly (check the browser console for errors, per the manual smoke test in `construction/build-and-test/integration-test-instructions.md`).
+
+## Future Work — Automatic Upload
+Once the hosting setup is finalized (FTP/SFTP details, and whether this frontend shares a domain/app with a future back-end and CMS front-end — see `deployment-plan.md`'s "Open Item"), replace the placeholder step in the `deploy` job with an actual upload step (e.g. an FTP/SFTP action, or a shell-based upload using `lftp`/`curl`), using Gitea Actions Secrets for credentials and Variables for host/paths. At that point, decide whether the trigger should stay manual or become automatic (e.g. on push to `release/*` or on tag).
@@ -0,0 +1,30 @@
+# Deployment Plan
+
+## Chosen Method
+**A manually-triggered Gitea Actions pipeline** (`workflow_dispatch`) that runs the build/test/lint gate and then packages the `dist/` build as a downloadable artifact. This is an interim setup, deliberately simplified per user feedback after the initial plan: no automatic upload to a host yet — that will be added later once the hosting details are finalized (see "Open Item" below).
+
+## How It Works
+1. You manually create a `release/*` branch when you want to cut a release (e.g. `release/1.0.0`), following your own git flow.
+2. You manually trigger the pipeline (`Build, Test and Package Release`) from Gitea's Actions UI, picking the branch/ref to run it against (typically the release branch).
+3. The pipeline always runs `build-and-test` first (install, lint, unit tests, build) as a gate.
+4. If that succeeds, the `deploy` job downloads the build and republishes it as a `release-dist` artifact, ready to download and upload to the host by hand for now.
+
+## Environments
+Simplified to a single flow for now (superseding the earlier dev/staging/production proposal, which is dropped per user feedback — **the staging/production auto-deploy jobs have been removed**):
+- No automated environment deployments exist yet.
+- Releases are prepared manually via `release/*` branches; the artifact produced by the pipeline is uploaded to the host manually until an automatic deploy step is added.
+
+## Automation Level
+Partially automated (intentionally, for now): build/test/lint and artifact packaging are automated once triggered, but **triggering itself is manual** (`workflow_dispatch`), and the actual upload to the host is also manual (download the `release-dist` artifact from the Gitea Actions run, then upload it yourself, e.g. via an FTP client). This is a deliberate interim step until the hosting setup is finalized.
+
+## Rollback Strategy
+Version control via git branches/releases: keep `release/*` branches (or tag them) so a previous release's artifact can be regenerated by re-running the pipeline against that branch/tag. See `rollback-plan.md`.
+
+## Secrets & Configuration
+Not yet needed — there is no automated upload step, so no host credentials are configured in Gitea Actions at this stage. When automatic deployment is added later, credentials should be stored as Gitea Actions Secrets (never committed to the repo), consistent with the original decision.
+
+## Open Item — Automatic Deploy Not Yet Implemented
+The `deploy` job currently only re-publishes the build as an artifact. Once you decide on the final hosting setup (FTP/SFTP details, and whether this frontend shares a domain/app with a future back-end and CMS front-end), the `deploy` job in `.gitea/workflows/deploy.yml` should be extended to actually upload `dist/` to the host (e.g. via an FTP/SFTP action or a shell-based upload step), reusing Gitea Actions Secrets/Variables for credentials and paths.
+
+## Verified Build Prerequisite
+This plan relies on the Build and Test stage already being verified (`construction/build-and-test/build-and-test-summary.md`): `pnpm run build` produces a static `dist/` bundle with no server-side requirements.
@@ -0,0 +1,27 @@
+# Rollback Plan
+
+## Strategy
+Since there is no automated upload step yet (deployment is manual — see `deployment-instructions.md`), "rollback" today means re-uploading a previous known-good build to the host by hand, rather than the pipeline reverting anything automatically.
+
+## Rolling Back the Live Site
+1. Identify the previous good `release/*` branch (or its last commit) that was actually uploaded to the host.
+2. Re-run the **Build, Test and Package Release** workflow manually against that branch/commit in Gitea Actions.
+3. Download the resulting `release-dist` artifact.
+4. Upload its contents to the host manually, overwriting the current (bad) files — the same manual step used for a normal deployment.
+5. Verify the live site reflects the rolled-back version.
+
+## Keeping Rollback Possible
+- Do not delete `release/*` branches after they've been deployed; keep them (or tag them, e.g. `release/1.0.0` → `v1.0.0`) so you can always re-run the pipeline against a known-good point.
+- Optionally keep a local/manual copy of the last few uploaded `dist/` artifacts as an extra safety net, since Gitea Actions artifacts expire after the configured retention period (currently 30 days, see `.gitea/workflows/deploy.yml`).
+
+## Database / Stateful Rollback Considerations
+Not applicable — this unit (`react-frontend-app`) is a static marketing site with no database and no server-side state. There is nothing to roll back beyond the static files themselves.
+
+## Future Work
+Once an automatic upload step is added (see `deployment-plan.md`'s "Open Item"), this rollback plan should be revisited: at that point, rollback can likely be automated too (e.g. re-triggering the pipeline for a previous branch/tag and letting it redeploy automatically, instead of a manual file upload).
+
+## Post-Rollback Checklist
+- [ ] Confirm the Gitea Actions run for the rollback build completed successfully
+- [ ] Confirm the live site reflects the rolled-back version (spot-check a recently changed section/copy)
+- [ ] Note the rollback (which release was restored and why) somewhere the team can find it
+- [ ] If the rollback was due to a bug, track a fix before re-attempting the failed release
@@ -12,7 +12,7 @@ B) Nee — deployment wordt elders geregeld of is niet nodig voor deze feature
 C) Niet zeker — stel een aanpak voor op basis van het project en ik beslis dan
 X) Anders (beschrijf na de [Answer]: tag hieronder)

-[Answer]:
+[Answer]: A

 ## Question 2: Deployment Method
 Hoe moet deze feature gedeployed worden?
@@ -23,7 +23,7 @@ C) On-premises / zelf gehoste server
 D) Handmatig / lokale deployment (bijv. build een artefact en upload het via FTP/SFTP naar een webhost)
 E) Anders (beschrijf na de [Answer]: tag hieronder)

-[Answer]:
+[Answer]:A, met Gitea Actions

 ## Question 3: Omgevingen
 Voor welke omgeving(en) moeten deployment-instructies gemaakt worden?
@@ -33,7 +33,7 @@ B) Staging en productie
 C) Development, staging en productie
 D) Anders (beschrijf na de [Answer]: tag hieronder)

-[Answer]:
+[Answer]:C

 ## Question 4: Automatiseringsniveau
 Welk automatiseringsniveau wil je?
@@ -43,7 +43,7 @@ B) Gedeeltelijk geautomatiseerd (bijv. build lokaal, upload automatisch via een
 C) Volledig handmatige, gedocumenteerde stappen (bijv. build lokaal, zelf uploaden via FTP-client)
 D) Anders (beschrijf na de [Answer]: tag hieronder)

-[Answer]:
+[Answer]:A

 ## Question 5: Rollback-strategie
 Hoe moet een mislukte deployment teruggedraaid kunnen worden?
@@ -53,7 +53,7 @@ B) Versiebeheer via tags/releases in git, opnieuw builden vanaf een eerdere tag
 C) Geen expliciete rollback nodig (statische site, snel opnieuw te builden en uploaden)
 D) Anders (beschrijf na de [Answer]: tag hieronder)

-[Answer]:
+[Answer]:B

 ## Question 6: Doelhost en overdrachtsmethode (alleen relevant bij handmatige/lokale deployment)
 Welke webhost/host wordt gebruikt en hoe komt het build-artefact daar terecht?
@@ -64,7 +64,7 @@ C) Upload via het controlepaneel van de hostingprovider (bijv. cPanel file manag
 D) Nog niet bekend — stel een generieke FTP/SFTP-aanpak voor die ik later kan invullen
 E) Anders (beschrijf na de [Answer]: tag hieronder)

-[Answer]:
+[Answer]:D, ik wil bij mijnhostingpartrner.nl, maar ik weet niet precies hoe zij te werk gaan. Er komt namelijk ook nog een back-end en een front-end voor het CMS. Dus ik moet even kijken of ik dat allemaal onder 1 domein kan laten vallen en als 1 app kan opzetten ipv 3 losse applicaties.

 ## Question 7: Opslag van inloggegevens (alleen relevant bij handmatige/lokale deployment)
 Waar worden de inloggegevens voor de FTP/SFTP-overdracht bewaard? (Nooit credentials hardcoden in gegenereerde instructies.)
@@ -74,4 +74,4 @@ B) In environment variables op de machine die deployed (bijv. voor een toekomsti
 C) Nog niet bepaald — vermeld dit als open actiepunt in de instructies
 D) Anders (beschrijf na de [Answer]: tag hieronder)

-[Answer]:
+[Answer]: D, Als Actions Secrets van Gitea