Skip to main content
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
  • Enable automated rollbacks with confidence

​
File Location

Create a file named <service-name>-release.ryvn.yaml at the root of your repository. The CLI automatically discovers this file when creating a release — no flags needed. For example, if your service is called my-service: 
my-repo/
├── my-service-release.ryvn.yaml   # auto-discovered by the CLI
├── Chart.yaml
└── ...

# The CLI finds my-service-release.ryvn.yaml automatically
ryvn create release my-service 1.2.3 --channel dev
You can also point to a file explicitly with -f: 
ryvn create release my-service 1.2.3 --channel dev -f path/to/metadata.yaml
The file can be YAML (.yaml, .yml) or JSON (.json).

​
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:
  - name: app
    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:
  - name: app
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

dependencies:
  - service: postgres-db
    minVersion: "1.0.0"
    maxVersion: "2.x.x"
    optional: false
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.
When deploying with Helm charts, there are typically two common patterns for versioning and pulling images:The simplest approach is to keep your container image tag synchronized with your Helm chart version. This makes reasoning easier since the chart version and image version are always the same.Configure your Helm templates to use the chart’s AppVersion:
# templates/deployment.yaml
spec:
  containers:
    - name: app
      image: "{{ .Values.image | default "ghcr.io/my-org/my-app" }}:{{ .Values.imageTag | default .Chart.AppVersion }}"
When you create a release, Ryvn uses that version for both the chart and the default image tag:
# Creates chart version 1.2.3, which pulls image my-app:1.2.3
ryvn create release my-service 1.2.3 --channel dev

​
Approach 2: Decouple Chart and Image Versions

If you need different versions for your chart and container image, specify the exact image in release metadata and reference it in your configuration.Step 1: Reference the artifact in your installation config:
kind: ServiceInstallation
metadata:
  name: my-service-production
spec:
  service: my-service
  environment: production
  config: |
    image: {{ .ryvn.release.images.app.repo }}:{{ .ryvn.release.images.app.tag }}
Alternatively, reference it directly in your Helm chart using .Values.ryvn:
# In your Helm chart: templates/deployment.yaml
spec:
  containers:
    - name: app
      image: {{ .Values.ryvn.release.images.app.repo }}:{{ .Values.ryvn.release.images.app.tag }}
Step 2: Create release with artifact metadata:
# release-metadata.yaml
artifacts:
  - name: app
    image:
      repository: ghcr.io/my-org/my-app
      tag: "v2023.11.14-abc123"

ryvn create release my-service 1.2.3 \
  --channel dev \
  -f release-metadata.yaml
Ryvn automatically passes release metadata as values, ensuring the correct container image is deployed regardless of the chart version.
For teams migrating from imperative CD pipelines (like GitHub Actions), Approach 1 provides the smoothest transition—just version your images to match your chart versions.

​
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)
dependencies:
    # Exact version requirement
    - service: postgres-db
      minVersion: "1.0.0"
      maxVersion: "1.0.0"
      optional: false
    
    # Version range (2.0.0 to 3.0.0)
    - service: user-service
      minVersion: "2.0.0"
      maxVersion: "3.0.0"
      optional: false
    
    # Wildcard range (any 2.x.x version)
    - service: redis-cache
      minVersion: "2.0.0"
      maxVersion: "2.x.x"
      optional: false
    
    # Unbounded range (any version >= 1.0.0)
    - service: monitoring-service
      minVersion: "1.0.0"
      maxVersion: "*"
      optional: true

​
Defining Dependencies

Add dependencies to your release metadata using version ranges: 
artifacts:
  - name: app
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

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

​
Dependency Resolution

Ryvn automatically resolves dependencies during deployment:
  1. Order calculation: Determines the optimal deployment order
  2. Health checks: Ensures dependent services are healthy before proceeding
  3. 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:
  - name: app
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"

dependencies:
  - service: user-service
    minVersion: "2.0.0"
    maxVersion: "2.x.x"
    optional: false

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

​
Troubleshooting

​
Common Issues

Ensure the artifact repository and tag are accessible from Ryvn’s infrastructure. Check registry credentials and network connectivity.
Verify that all dependent services exist and are accessible. Check version compatibility and service health.
Check the metadata format against the schema. Ensure all required fields are present and valid.

​
Debugging Metadata

Use Ryvn’s CLI to inspect release metadata: 
# View release metadata
ryvn get release my-service 1.2.3 -o json