Skip to content

docs: document app release pagination and retention cleanup #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jona62 merged 1 commit into from
Oct 3, 2026
Merged

docs: document app release pagination and retention cleanup #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions api-reference/app-releases/list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,7 @@ openapi: "/openapi/app-releases-api.json GET /api/v1/workspaces/{id}/app-release
---

Requires the v0.13 app-release capability for your account. See [app release workflows](/deploy/overview) for preparation, activation, and recovery.

Results are ordered by creation time, newest first. Set `max_results` to request a page size; it defaults to 50 and is clamped to 1–200. Pass the response's opaque `next_cursor` as `cursor` to fetch the next page. When `next_cursor` is absent, the list is complete.

Expired releases are deleted during [retention cleanup](/deploy/app-rollback#retention), including their records and logs. Pagination applies to the retained history.
8 changes: 8 additions & 0 deletions deploy/app-rollback.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,14 @@ rig app-release logs --workspace my-project --release <RELEASE_ID>

Choose a known-good retained release that belongs to this workspace. Review its application set and configuration before activation.

## Retention

Each deployment owner keeps the newest successful release record for each of its three most recently used distinct artifacts. Repeated rollback records for the same artifact are removed. Releases being prepared or activated remain available while the operation runs; ready candidates and failed releases expire after 24 hours.

Retention deletes expired release records, stored configuration, diagnostic logs, and obsolete deployment idempotency records. Cleanup runs after an operation finishes and every ten minutes on the owning compute node, including stopped workspaces. Guest artifact removal waits for the workspace to run. After collection, an expired release ID returns HTTP 404 from the release and logs APIs; deploy again with a new deployment ID when another attempt is needed.

The [release list API](/api-reference/app-releases/list) returns up to 50 records by default, with a maximum page size of 200. Pass its opaque `next_cursor` back as `cursor` to continue. Results stay ordered by creation time, newest first. The CLI follows each page when running `rig app-release ls`.

## Roll back

```bash
Expand Down
120 changes: 116 additions & 4 deletions openapi/app-releases-api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,17 +24,52 @@
"tags": [
"App releases"
],
"description": "List app releases newest first using a stable creation-time cursor. Expired records are removed by retention.",
"operationId": "list",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Workspace ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "max_results",
"in": "query",
"description": "Maximum number of items to return. Defaults to 50; values are clamped to the range 1–200.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
{
"name": "cursor",
"in": "query",
"description": "Opaque cursor returned by a prior call's `next_cursor`. Omit on the\nfirst page.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "App release result",
"description": "App releases page",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListResponse"
"$ref": "#/components/schemas/Page_AppRelease"
}
}
}
},
"400": {
"description": "Invalid cursor"
}
},
"security": [
Expand Down Expand Up @@ -338,17 +373,94 @@
},
"additionalProperties": false
},
"ListResponse": {
"Page_AppRelease": {
"type": "object",
"description": "Paginated response envelope. `next_cursor` is omitted on the last page.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AppRelease"
"type": "object",
"required": [
"id",
"is_current",
"can_rollback",
"workspace_id",
"user_id",
"owner_key",
"idempotency_key",
"status",
"artifact_release_id",
"apps",
"created_at",
"updated_at"
],
"properties": {
"apps": {},
"artifact_release_id": {
"type": "string"
},
"can_rollback": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"error": {
"type": [
"string",
"null"
]
},
"id": {
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"is_current": {
"type": "boolean"
},
"owner_key": {
"type": "string"
},
"previous_release_id": {
"type": [
"string",
"null"
]
},
"source_commit": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"user_id": {
"type": "string"
},
"workspace_id": {
"type": "string"
}
}
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
}
},
Expand Down
Loading