Update

2026-07-24 20:29:23 +02:00
commit 66060348da
107 changed files with 14771 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Server status endpoint contract
+
+A workflow can report success while the wrong application version is running.
+ForgeFlow therefore supports a small server-side endpoint that independently
+reports the deployed commit.
+
+## Canonical response
+
+```json
+{
+  "repository": "jens/example-app",
+  "environment": "production",
+  "request_id": "3a6ed71c-d52d-4d8d-9678-96e0c9456a81",
+  "commit_sha": "0123456789abcdef0123456789abcdef01234567",
+  "previous_sha": "89abcdef0123456789abcdef0123456789abcdef",
+  "requested_sha": "0123456789abcdef0123456789abcdef01234567",
+  "deployed_at": "2026-07-24T13:00:00Z",
+  "health": "healthy",
+  "last_exit_code": 0
+}
+```
+
+Required for exact version verification:
+
+- `commit_sha`: full 40–64 character hexadecimal commit identity.
+
+Recommended:
+
+- `previous_sha`: previous successful commit used by rollback;
+- `requested_sha`: SHA requested by the latest deployment attempt;
+- `request_id`: ForgeFlow operation correlation identifier;
+- `deployed_at`: ISO-8601 timestamp;
+- `health`: `healthy`, `deploying` or `unhealthy`;
+- `last_exit_code`: server entry-point result, with `0` for success;
+- `repository` and `environment`: useful for human consistency checks.
+
+ForgeFlow also accepts `commitSha`, `sha`, `previousSha`, `requestId` and nested
+`version.sha`, but canonical snake-case fields are preferred.
+
+## Isolation
+
+Serve the endpoint independently from the deployed application when practical.
+A static JSON file exposed by the reverse proxy remains readable when the
+application fails to boot. The included deployment script writes it atomically.
+
+The JSON file is non-secret and can be served read-only. Do not include tokens,
+host credentials, environment variables, registry secrets or stack traces.
+
+## Profile configuration
+
+Set both URLs when available:
+
+- **Status URL**: returns this document and exact live SHA;
+- **Healthcheck URL**: returns a successful HTTP status only when the application
+  is operational.
+
+After an Actions run succeeds, ForgeFlow checks both. It marks the operation
+failed when the healthcheck is unhealthy or the server reports another SHA than
+the requested deployment.