git.stella-ops.org/docs/modules/release-orchestrator/api/releases.md

Release Management APIs

API endpoints for managing components, versions, and release bundles.

Status: Planned (not yet implemented) Source: Architecture Advisory Section 6.3.3 Related Modules: Release Manager Module, Integration Hub

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:

{
  "name": "api",
  "displayName": "API Service",
  "imageRepository": "myorg/api",
  "registryIntegrationId": "uuid",
  "versioningStrategy": "semver",
  "defaultChannel": "stable"
}

Response: 201 Created

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

{
  "forceRefresh": true
}

Response: 200 OK

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

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

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

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

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

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

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

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

{
  "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
• Release Manager Module
• Integration Hub
• Design Principles