ForgeFlow/docs/STATUS_ENDPOINT.md

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

{
  "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.