60 lines
2.1 KiB
Markdown
60 lines
2.1 KiB
Markdown
# 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.
|