agiledancers/specs/in_review/S6_deployment-gitea-action-to-production.md

# S6 — Manual versioned production deployment through Gitea

Status: IN_REVIEW

Agreed after the grill-me interview; shared understanding confirmed.

## User story

As a developer, I want to manually release a verified main-branch build from
Gitea to the Synology, choosing a semantic version increment, so that I control
when the launching partner receives a new production version and can recover
the previous working version when necessary.

This replaces the original automatic-deployment story. Build, test and image
publication remain automatic; production deployment requires a deliberate action.

## Existing foundation and scope

- Extend the implemented S4 pipeline, which verifies builds and publishes matching
  frontend/backend images with immutable full commit SHA tags for successful main
  builds. Deploy those existing images without rebuilding them.
- Target one production Docker Compose stack on the Synology (`linux/amd64`).
  The existing Gitea runner triggers deployment over SSH.
- Keep one active backend. A brief restart interruption is acceptable, including
  interruption of a scheduling calculation; the user may restart the calculation.
- Production is private to the LAN or existing VPN. A configurable Synology
  hostname/IP and port provide access without an application login.
- Publish only the frontend port. Keep the backend reachable within the Compose
  network; route browser API requests through the frontend proxy.
- Actual server addresses, ports, paths and account configuration must be
  established and documented during implementation, without committing secrets.

## Manual release interface

Provide a separate **Deploy production** workflow using Gitea's native manual
workflow trigger (`workflow_dispatch`). Its Run workflow popup offers:

- **New release** or **Retry release** mode.
- For a new release: a release-type choice of **patch**, **minor** or **major**.
- For a retry: the existing release version tag.

Provide a manual rollback action for the previous successful production release.
The native Gitea button need not be renamed or embedded into an existing build
run. Gitea 1.25.4 supports the required modal and choice inputs.

### New release eligibility and ordering

- Run the release workflow from main. Branch builds cannot deploy production.
- Pin the current main SHA at workflow start. Require successful build checks and
  image publication for that exact SHA; missing or failed verification leaves
  production unchanged. Both images must be retrievable before replacement.
- Recheck main immediately before changing production. If it has advanced, abort
  without changing production. Once replacement starts, finish deployment or
  recovery using the pinned SHA; later commits require another manual release.
- Serialize deployment, recovery, rollback, version allocation and tag creation.
  Prevent stale runs from replacing newer successful production releases.
- Reject a new release for an already release-tagged commit and direct the
  operator to retry or rollback instead. Repeated clicks must not create extra
  versions or deploy out of order.

## Semantic versioning and Git tags

- Use one shared application version for frontend and backend, represented by
  an immutable annotated Git tag `vMAJOR.MINOR.PATCH` on the verified SHA.
- The first release is `v1.0.0`. Inspect remote tags before initialization and
  fail visibly on conflicting existing history instead of overwriting it.
- Subsequent releases increment the highest existing release version tag,
  including tags belonging to failed deployments. A rollback does not lower the
  version baseline. Patch increments PATCH; minor increments MINOR and resets
  PATCH; major increments MAJOR and resets MINOR and PATCH.
- For example, from `v1.2.3`, the choices produce `v1.2.4`, `v1.3.0` or `v2.0.0`.
- After checking eligibility and image availability, create the tag before
  changing production. This establishes tag-writing access before replacement.
  Never move a release tag or reuse its version for different code.
- Retain a tag if deployment subsequently fails or aborts. Record the outcome so
  a tag is not mistaken for proof of successful production deployment.
- A retry reuses the existing tag and exact SHA without allocating a version.
  Require successful build verification and matching available images. Retrying
  an older release must not supersede a newer successful release. Retrying an
  existing release is an explicit exception to the current-main requirement.
- Rollback restores an existing release and creates no new version. It is an
  explicit exception to the prohibition on replacing newer code with older code.
- Continue using SHA-tagged container images; the Git release tag and deployment
  record map the semantic version to that SHA and image pair.
- Maven/npm version fields and automated changelog generation are outside S6.
  Do not introduce a version-bump commit and rebuild into the release path.

## Deployment checks and recovery

- Retrieve the candidate images and validate prerequisites before replacing the
  running release. Frontend and backend must use the same selected commit SHA.
- Within five minutes of starting the replacement, require all of:
  - Backend readiness succeeds.
  - The frontend page is served.
  - A read-only API request succeeds through the frontend proxy.
  - Both running containers match the selected SHA/image pair.
- Checks must not create or modify user data. Log the selected SHA/version and
  final outcome.
- A failed candidate automatically restores the previous successful image pair
  and checks its health. The workflow remains failed even if recovery succeeds.
- Retain references to the current and previous successful releases and ensure
  their images remain available. A manual rollback targets that previous release;
  fail before modifying production if its required images cannot be retrieved.
- If the first deployment fails with no previous release, or recovery itself
  fails, stop with a clear failure report and manual recovery instructions.
  Preserve diagnostics; do not enter an endless deployment/recovery loop.
- Record successful production release state separately from allocated Git tags,
  so failed attempts do not become the rollback target.

## Data policy and S16/S17 boundaries

S16 is **not a prerequisite** for S6. Until S16 is implemented, application state
is held in memory and may be lost during deployment, rollback or recovery. The
launching-partner phase explicitly accepts this limitation. Restoring old images
does not restore lost data.

- State the temporary data-loss limitation in the workflow description and
  deployment runbook. The operator is responsible for informing the launching
  partner; do not add a further approval step to each deployment.
- After S16 is implemented, deployments and rollbacks must preserve saved data.
  Keep persistent storage outside replaceable containers and do not delete it
  during deployment or recovery.
- After S16, ordinary release and rollback paths require database compatibility
  with the previous application version. Incompatible migrations require a
  separately planned maintenance procedure; image rollback cannot undo them.
- Database backup and restore remain separate S17 work. S6 does not promise
  recovery of data lost before persistence or through storage loss.

## Credentials and operational documentation

- Use a dedicated Synology deployment account with SSH key authentication and a
  pinned server host key. Document the narrowly required deployment permissions.
- Use a separate registry credential with pull access for production and a
  credential with the required repository permission for release-tag creation.
- Store deployment secrets in Gitea Actions secrets, provision server-side
  credentials securely where needed, and keep secret values out of Git and logs.
- Document initial provisioning, configuration, release/retry/rollback operation,
  credential setup, health checks, release records and manual recovery.
- Retain deployment diagnostics for fourteen days, including failed deployment
  and recovery outcomes, without exposing credentials.

## Acceptance criteria

- [x] Successful main builds still automatically verify and publish matching SHA
      images; publishing does not automatically change production.
- [x] Gitea's manual workflow form provides new/retry mode and the appropriate
      release-type or existing-tag inputs; invalid combinations fail clearly.
- [x] The first release and subsequent patch/minor/major releases allocate the
      agreed versions and immutable annotated remote Git tags on verified SHAs.
- [x] Duplicate new releases, tag conflicts, concurrent attempts, stale main
      snapshots and older pending deployments cannot overwrite release identity
      or replace a newer successful release.
- [x] An unverified release or missing image is rejected before production changes;
      branch builds cannot deploy production.
- [x] A real Synology deployment serves the frontend and proxied API over the
      private endpoint, with both containers running the selected image pair.
- [x] Readiness, frontend, proxied read-only API and image-identity checks establish
      success within five minutes or trigger recovery.
- [x] A deliberately failed release restores the previous successful version,
      while the workflow reports failure. Failed first deployment and failed
      recovery produce actionable diagnostics and manual recovery instructions.
- [x] A failed release can be retried with its existing tag/SHA without allocating
      another version or superseding a newer successful release.
- [x] Manual rollback demonstrably restores the previous successful release with
      no new version, and required retained images are available.
- [x] The temporary pre-S16 data-loss policy is visible in workflow documentation
      and the runbook. Once S16 applies, demonstrate saved data surviving both
      deployment and rollback, including the migration compatibility requirement.
      The latter is conditional S16 acceptance and is not applicable yet.
- [x] Server setup and operational recovery documentation are usable; diagnostics
      and release outcomes are retained for fourteen days without secrets.

## Implementation and evidence

This specification records the confirmed design. The evidence combines automated
behavior tests, real Gitea production release/guard runs and isolated real NAS
fault tests. Their distinct scopes and the virtual-tag boundary of the isolated
tests are documented in `docs/s6-validation.md`. Configuration alone does not
complete S6.

Implementation PR #12 is merged. Production `v1.0.0` runs at
`http://192.168.2.28:8088` following a successful main build and real manual Gitea
deployment. Native duplicate/branch guards and downloadable artifacts were
verified. Twelve isolated real NAS checks cover recovery, retry, distinct-version
rollback, failure guards and manual recovery; they use separate state/containers
and virtual test tags, without changing production. The test resources have been
removed. See `docs/s6-validation.md` for run links, digests, evidence boundaries
and the conditional S16 data-persistence acceptance. S6 is ready for review.