add release orchestrator docs and sprints gaps fills
This commit is contained in:
345
docs/modules/release-orchestrator/api/releases.md
Normal file
345
docs/modules/release-orchestrator/api/releases.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# Release Management APIs
|
||||
|
||||
> API endpoints for managing components, versions, and release bundles.
|
||||
|
||||
**Status:** Planned (not yet implemented)
|
||||
**Source:** [Architecture Advisory Section 6.3.3](../../../product/advisories/09-Jan-2026%20-%20Stella%20Ops%20Orchestrator%20Architecture.md)
|
||||
**Related Modules:** [Release Manager Module](../modules/release-manager.md), [Integration Hub](../modules/integration-hub.md)
|
||||
|
||||
## Overview
|
||||
|
||||
The Release Management API provides endpoints for managing container components, version tracking, and release bundle creation. All releases are identified by immutable OCI digests, ensuring cryptographic verification throughout the deployment pipeline.
|
||||
|
||||
> **Design Principle:** Release identity is established via digest, not tag. Tags are human-friendly aliases; digests are the source of truth.
|
||||
|
||||
---
|
||||
|
||||
## Component Endpoints
|
||||
|
||||
### Create Component
|
||||
|
||||
**Endpoint:** `POST /api/v1/components`
|
||||
|
||||
Registers a new container component for release management.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"name": "api",
|
||||
"displayName": "API Service",
|
||||
"imageRepository": "myorg/api",
|
||||
"registryIntegrationId": "uuid",
|
||||
"versioningStrategy": "semver",
|
||||
"defaultChannel": "stable"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `201 Created`
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "api",
|
||||
"displayName": "API Service",
|
||||
"imageRepository": "myorg/api",
|
||||
"registryIntegrationId": "uuid",
|
||||
"versioningStrategy": "semver",
|
||||
"createdAt": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
### List Components
|
||||
|
||||
**Endpoint:** `GET /api/v1/components`
|
||||
|
||||
**Response:** `200 OK` - Array of components
|
||||
|
||||
### Get Component
|
||||
|
||||
**Endpoint:** `GET /api/v1/components/{id}`
|
||||
|
||||
### Update Component
|
||||
|
||||
**Endpoint:** `PUT /api/v1/components/{id}`
|
||||
|
||||
### Delete Component
|
||||
|
||||
**Endpoint:** `DELETE /api/v1/components/{id}`
|
||||
|
||||
### Sync Versions
|
||||
|
||||
**Endpoint:** `POST /api/v1/components/{id}/sync-versions`
|
||||
|
||||
Triggers a refresh of available versions from the container registry.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"forceRefresh": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{
|
||||
"synced": 15,
|
||||
"versions": [
|
||||
{
|
||||
"tag": "v2.3.1",
|
||||
"digest": "sha256:abc123...",
|
||||
"semver": "2.3.1",
|
||||
"channel": "stable",
|
||||
"pushedAt": "2026-01-09T10:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### List Component Versions
|
||||
|
||||
**Endpoint:** `GET /api/v1/components/{id}/versions`
|
||||
|
||||
**Query Parameters:**
|
||||
- `channel` (string): Filter by channel (`stable`, `beta`, `rc`)
|
||||
- `limit` (number): Maximum versions to return
|
||||
|
||||
**Response:** `200 OK` - Array of version maps
|
||||
|
||||
---
|
||||
|
||||
## Version Map Endpoints
|
||||
|
||||
### Create Version Map
|
||||
|
||||
**Endpoint:** `POST /api/v1/version-maps`
|
||||
|
||||
Manually assign a semver and channel to a tag/digest.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"componentId": "uuid",
|
||||
"tag": "v2.3.1",
|
||||
"semver": "2.3.1",
|
||||
"channel": "stable"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `201 Created`
|
||||
|
||||
### List Version Maps
|
||||
|
||||
**Endpoint:** `GET /api/v1/version-maps`
|
||||
|
||||
**Query Parameters:**
|
||||
- `componentId` (UUID): Filter by component
|
||||
- `channel` (string): Filter by channel
|
||||
|
||||
---
|
||||
|
||||
## Release Endpoints
|
||||
|
||||
### Create Release
|
||||
|
||||
**Endpoint:** `POST /api/v1/releases`
|
||||
|
||||
Creates a new release bundle with specified component versions.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"name": "myapp-v2.3.1",
|
||||
"displayName": "My App 2.3.1",
|
||||
"components": [
|
||||
{ "componentId": "uuid", "version": "2.3.1" },
|
||||
{ "componentId": "uuid", "digest": "sha256:def456..." },
|
||||
{ "componentId": "uuid", "channel": "stable" }
|
||||
],
|
||||
"sourceRef": {
|
||||
"scmIntegrationId": "uuid",
|
||||
"repository": "myorg/myapp",
|
||||
"branch": "main",
|
||||
"commitSha": "abc123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `201 Created`
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "myapp-v2.3.1",
|
||||
"displayName": "My App 2.3.1",
|
||||
"status": "draft",
|
||||
"components": [
|
||||
{
|
||||
"componentId": "uuid",
|
||||
"componentName": "api",
|
||||
"version": "2.3.1",
|
||||
"digest": "sha256:abc123...",
|
||||
"channel": "stable"
|
||||
}
|
||||
],
|
||||
"createdAt": "2026-01-10T14:23:45Z",
|
||||
"createdBy": "user-uuid"
|
||||
}
|
||||
```
|
||||
|
||||
### Create Release from Latest
|
||||
|
||||
**Endpoint:** `POST /api/v1/releases/from-latest`
|
||||
|
||||
Convenience endpoint to create a release from the latest versions of all (or specified) components.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"name": "myapp-latest",
|
||||
"channel": "stable",
|
||||
"componentIds": ["uuid1", "uuid2"],
|
||||
"pinFrom": {
|
||||
"environmentId": "uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `201 Created` - Release with resolved digests
|
||||
|
||||
### List Releases
|
||||
|
||||
**Endpoint:** `GET /api/v1/releases`
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string): Filter by status (`draft`, `ready`, `promoting`, `deployed`, `deprecated`)
|
||||
- `componentId` (UUID): Filter by component inclusion
|
||||
- `page` (number): Page number
|
||||
- `pageSize` (number): Items per page
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "myapp-v2.3.1",
|
||||
"status": "deployed",
|
||||
"componentCount": 3,
|
||||
"createdAt": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"totalCount": 150,
|
||||
"totalPages": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Release
|
||||
|
||||
**Endpoint:** `GET /api/v1/releases/{id}`
|
||||
|
||||
**Response:** `200 OK` - Full release with component details
|
||||
|
||||
### Update Release
|
||||
|
||||
**Endpoint:** `PUT /api/v1/releases/{id}`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"displayName": "Updated Display Name",
|
||||
"metadata": { "key": "value" },
|
||||
"status": "ready"
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Release
|
||||
|
||||
**Endpoint:** `DELETE /api/v1/releases/{id}`
|
||||
|
||||
### Get Release State
|
||||
|
||||
**Endpoint:** `GET /api/v1/releases/{id}/state`
|
||||
|
||||
Returns the deployment state of a release across environments.
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{
|
||||
"environments": [
|
||||
{
|
||||
"environmentId": "uuid",
|
||||
"environmentName": "Development",
|
||||
"status": "deployed",
|
||||
"deployedAt": "2026-01-09T10:00:00Z"
|
||||
},
|
||||
{
|
||||
"environmentId": "uuid",
|
||||
"environmentName": "Staging",
|
||||
"status": "deployed",
|
||||
"deployedAt": "2026-01-10T08:00:00Z"
|
||||
},
|
||||
{
|
||||
"environmentId": "uuid",
|
||||
"environmentName": "Production",
|
||||
"status": "not_deployed"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Deprecate Release
|
||||
|
||||
**Endpoint:** `POST /api/v1/releases/{id}/deprecate`
|
||||
|
||||
Marks a release as deprecated, preventing new promotions.
|
||||
|
||||
**Response:** `200 OK` - Updated release with `status: deprecated`
|
||||
|
||||
### Compare Releases
|
||||
|
||||
**Endpoint:** `GET /api/v1/releases/{id}/compare/{otherId}`
|
||||
|
||||
Compares two releases to identify component differences.
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{
|
||||
"added": [
|
||||
{ "componentId": "uuid", "componentName": "worker" }
|
||||
],
|
||||
"removed": [
|
||||
{ "componentId": "uuid", "componentName": "legacy-service" }
|
||||
],
|
||||
"changed": [
|
||||
{
|
||||
"component": "api",
|
||||
"fromVersion": "2.3.0",
|
||||
"toVersion": "2.3.1",
|
||||
"fromDigest": "sha256:old...",
|
||||
"toDigest": "sha256:new..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Status Code | Description |
|
||||
|-------------|-------------|
|
||||
| `400` | Invalid release configuration |
|
||||
| `404` | Release or component not found |
|
||||
| `409` | Release name already exists |
|
||||
| `422` | Cannot resolve component version |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Promotions API](promotions.md)
|
||||
- [Release Manager Module](../modules/release-manager.md)
|
||||
- [Integration Hub](../modules/integration-hub.md)
|
||||
- [Design Principles](../design/principles.md)
|
||||
Reference in New Issue
Block a user