Release Metadata

Release metadata allows you to define additional information about your service releases that Ryvn uses for automated deployment, dependency management, and migration path computation. This includes container artifacts, service dependencies, and database migration schemas.

Overview

Release metadata is stored as JSON in the release_metadata field of each service release. This metadata helps Ryvn:

Track exact artifacts used in each release (container images, Helm charts, etc.)
Manage service dependencies and ensure proper deployment order
Compute valid migration paths between versions
Enable automated rollbacks with confidence

Using Release Metadata in ryvn.yaml

Release metadata is defined in your ryvn.yaml file under the services block. This allows you to version-control your release metadata alongside your application code and define service-specific release information.

Service Configuration with Metadata

apiVersion: v1

services:
  - name: my-web-app
    type: web-server.v1
    repository:
      type: github
      owner: my-org
      repo: my-web-app
    # Release metadata for this service
    releaseMetadata:
      artifacts:
        - type: container-image
          image:
            repository: ghcr.io/my-org/my-app
            tag: "{{ .version }}"
      dependencies:
        services:
          - name: postgres-db
            minVersion: "1.0.0"
            maxVersion: "2.x.x"   # wildcard for any 2.x.x version
          - name: redis-tf
            minVersion: "6.0.0"
            maxVersion: "7.x.x"   # wildcard for any 7.x.x version
      migrations:
        - version: 4  # Schema version 4 is supported
        - version: 5  # Schema version 5 is supported
        - version: 6  # Schema version 6 is supported

Release Artifacts

Release artifacts define the exact artifacts (like container images) that are part of a release. This ensures reproducible deployments and enables Ryvn to track what’s actually running in each environment.

Container Image Artifacts

For web server and Docker image services, you can specify the exact container images used in a release:

artifacts:
  - type: container-image
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

Creating Releases with Metadata

You can create releases with metadata using the Ryvn CLI. The metadata can be provided via a file or inline:

# Create release with metadata from file
ryvn create release my-service 1.2.3 \
  --channel dev \
  --channel staging \
  -f release-metadata.yaml

release-metadata.yaml:

artifacts:
  - type: container-image
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

dependencies:
  services:
    - name: postgres-db
      minVersion: "1.0.0"
      maxVersion: "2.x.x"

migrations:
  - version: 4
  - version: 5
  - version: 6

# Create release with metadata from file
ryvn create release my-service 1.2.3 \
  --channel dev \
  --channel staging \
  -f release-metadata.yaml

release-metadata.yaml:

artifacts:
  - type: container-image
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

dependencies:
  services:
    - name: postgres-db
      minVersion: "1.0.0"
      maxVersion: "2.x.x"

migrations:
  - version: 4
  - version: 5
  - version: 6

# Create release with inline metadata
ryvn create release my-service 1.2.3 \
  --channel dev \
  --channel staging \
  --metadata '{"artifacts":[{"type":"container-image","image":{"repository":"ghcr.io/my-org/my-app","tag":"1.2.3"}}]}'

The metadata file can be in YAML or JSON format. When using the -f flag, Ryvn will automatically detect the format based on the file extension. The --metadata flag expects JSON format for inline metadata.

Service Dependencies

Service dependencies define the relationships between services and ensure proper deployment order. This is crucial for complex applications with multiple interconnected services.

Dependency Types

Ryvn supports several types of service dependencies:

Database dependencies: Services that require a database to be available
API dependencies: Services that depend on other services’ APIs
Infrastructure dependencies: Services that require specific infrastructure components

Version Range Format

Dependencies use version ranges with minVersion and maxVersion fields:

Exact version: minVersion: "2.1.0", maxVersion: "2.1.0"
Version range: minVersion: "2.0.0", maxVersion: "3.0.0"
Wildcard support: minVersion: "2.0.0", maxVersion: "3.x.x" (any 3.x.x version)
Unbounded range: minVersion: "2.0.0", maxVersion: "*" (any version >= 2.0.0)

Version Range Examples

dependencies:
  services:
    # Exact version requirement
    - name: postgres-db
      minVersion: "1.0.0"
      maxVersion: "1.0.0"
    
    # Version range (2.0.0 to 3.0.0)
    - name: user-service
      minVersion: "2.0.0"
      maxVersion: "3.0.0"
    
    # Wildcard range (any 2.x.x version)
    - name: redis-cache
      minVersion: "2.0.0"
      maxVersion: "2.x.x"
    
    # Unbounded range (any version >= 1.0.0)
    - name: monitoring-service
      minVersion: "1.0.0"
      maxVersion: "*"

Defining Dependencies

Add dependencies to your release metadata using version ranges:

artifacts:
  - type: container-image
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

dependencies:
  services:
    - name: user-service
      minVersion: "2.0.0"
      maxVersion: "3.x.x"    # wildcard for any 3.x.x version
    - name: postgres-db
      minVersion: "1.0.0"
      maxVersion: "2.x.x"    # wildcard for any 2.x.x version

Dependency Resolution

Ryvn automatically resolves dependencies during deployment:

Order calculation: Determines the optimal deployment order
Health checks: Ensures dependent services are healthy before proceeding
Rollback coordination: Handles rollbacks across dependent services

Dependencies must be satisfied before a service can be deployed. Ryvn will block deployments if dependencies are unavailable or unhealthy.

Migration Schemas

Migration schemas define which database schema versions are supported by the current release. This enables Ryvn to compute valid migration paths and prevent rollbacks to unsupported schema versions.

Schema Version Support

Each release specifies a list of supported schema versions:

Current schema versions: The schema versions that this release supports
Migration path validation: Ryvn ensures rollbacks only target supported schema versions
Version compatibility: Prevents deployment to releases with incompatible schemas

Migration Schema Format

artifacts:
  - type: container-image
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

dependencies:
  services:
    - name: user-service
      minVersion: "2.0.0"
      maxVersion: "3.x.x"
      type: api

migrations:
  - version: 4  # Schema version 4 is supported
  - version: 5  # Schema version 5 is supported
  - version: 6  # Schema version 6 is supported

Migration Path Computation

Ryvn uses the supported schema versions to:

Validate rollback targets: Ensure rollbacks only target supported schema versions
Prevent incompatible deployments: Block deployments to releases with unsupported schemas
Calculate migration paths: Determine valid upgrade and rollback paths
Enforce schema compatibility: Ensure data integrity across releases

Schema Version Evolution

As your application evolves, you can add or remove supported schema versions:

# Release 1.2.0 supports schemas 4, 5, 6
migrations:
  - version: 4
  - version: 5
  - version: 6

# Release 1.3.0 supports schemas 5, 6, 7 (removed 4, added 7)
migrations:
  - version: 5
  - version: 6
  - version: 7

# Release 1.4.0 supports schemas 6, 7, 8 (removed 5, added 8)
migrations:
  - version: 6
  - version: 7
  - version: 8

When a schema version is removed from the supported list, Ryvn will prevent rollbacks to releases that only support that schema version. This ensures data integrity and prevents deployment to incompatible releases.

Schema Analysis

Ryvn analyzes the supported schema versions of both current and target releases

Compatibility Check

Validates that the target release supports the current schema version

Path Validation

Ensures rollback targets only supported schema versions

Deployment Decision

Allows or blocks deployment based on schema compatibility

Advanced Metadata Features

Custom Metadata

You can include custom metadata for your specific use cases:

artifacts:
  - type: container-image
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

dependencies:
  services:
    - name: user-service
      minVersion: "2.0.0"
      maxVersion: "3.x.x"
      type: api

migrations:
  - version: 4  # Schema version 4 is supported
  - version: 5  # Schema version 5 is supported
  - version: 6  # Schema version 6 is supported

custom:
  releaseNotes: "Added new user authentication features"
  breakingChanges:
    - "Removed deprecated API endpoints"
  featureFlags:
    - "new-auth-system"
  deploymentNotes: "Requires database migration"

Metadata Validation

Ryvn validates release metadata to ensure:

Artifact consistency: Artifacts match the service type
Dependency validity: Referenced services exist and are accessible
Migration compatibility: Migration scripts are valid SQL
Version compatibility: Dependencies are compatible with the release version

Metadata Inheritance

Release metadata can inherit from previous releases:

inheritFrom: "1.1.0"

artifacts:
  - type: container-image
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

dependencies:
  inherit: true
  additions:
    - name: new-service
      minVersion: "1.0.0"
      maxVersion: "2.x.x"
      type: api

Best Practices

Artifact Management

Use semantic versioning for all artifacts

Include checksums for artifact integrity

Tag artifacts with the same version as the release

Dependency Management

Keep dependencies minimal and well-defined

Use version ranges for flexible dependency resolution

Document breaking changes in dependencies

Migration Management

Test migrations in staging environments first

Include rollback scripts for all migrations

Estimate migration duration accurately

Use database transactions for atomic migrations

Metadata Maintenance

Keep metadata up-to-date with each release

Validate metadata before creating releases

Document custom metadata fields

Review and clean up old metadata periodically

Troubleshooting

Common Issues

Artifact Not Found

Dependency Resolution Failed

Migration Path Invalid

Metadata Validation Errors

Debugging Metadata

Use Ryvn’s CLI to inspect release metadata:

# View release metadata
ryvn releases get my-service 1.2.3 --metadata

# Validate metadata
ryvn releases validate my-service 1.2.3

# Compare metadata between versions
ryvn releases diff my-service 1.1.0 1.2.3

API Reference