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,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