Update

2026-07-24 20:29:23 +02:00
commit 66060348da
107 changed files with 14771 additions and 0 deletions
@@ -0,0 +1,58 @@
+# Deployment setup guide
+
+This guide connects one Gitea repository to one server environment without giving the desktop arbitrary shell access.
+
+## 1. Add fixed workflows
+
+Copy these examples into the repository:
+
+```text
+examples/gitea-actions/deploy.yml   -> .gitea/workflows/deploy.yml
+examples/gitea-actions/rollback.yml -> .gitea/workflows/rollback.yml
+```
+
+Change the runner label to the label registered for the target environment.
+
+## 2. Install the allowlisted server entry point
+
+Copy `examples/server/forgeflow-deploy` to `/usr/local/bin/forgeflow-deploy`, customize its repository/environment allowlist and make it root-owned:
+
+```bash
+sudo install -o root -g root -m 0755 forgeflow-deploy /usr/local/bin/forgeflow-deploy
+```
+
+Grant the runner account permission to execute only this entry point where elevation is needed. Do not grant unrestricted shell or Docker administration merely for ForgeFlow.
+
+## 3. Expose deployment status
+
+The example script writes an atomic JSON document beneath `/var/lib/forgeflow-status`. Serve the appropriate file at a fixed HTTPS URL, for example with `examples/server/nginx-forgeflow-status.conf`.
+
+See `STATUS_ENDPOINT.md` for the contract.
+
+## 4. Configure the ForgeFlow profile
+
+Open the repository, choose **Deployments** and add an environment with:
+
+- Name: `Production` or `Staging`.
+- Environment: the fixed workflow input.
+- Branch: usually `main`.
+- Workflow file: `deploy.yml`.
+- Rollback workflow: `rollback.yml`.
+- Status URL: the JSON endpoint.
+- Healthcheck URL: the application health endpoint.
+- Confirmation: enabled for production.
+
+## 5. Validate the complete path
+
+Test these scenarios before relying on production:
+
+1. Clean commit and push.
+2. Successful deployment to the exact SHA.
+3. Gitea runner failure.
+4. Application healthcheck failure.
+5. Server reports the wrong SHA.
+6. Second deployment while the lock is held.
+7. Rollback to the recorded previous SHA.
+8. Token without sufficient permissions.
+
+Keep a manual recovery path documented even after rollback works.