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
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"
      digest: "sha256:4f5c…"   # optional: the digest the registry reported on push

digest is the image’s immutable identity. A tag can be moved to different content later; a digest cannot, so a release that records one always refers to the exact bytes that were published. For a multi-platform image it is the digest of the image index, not of one platform’s manifest. Releases built with ryvn-build-action record the digest automatically. If you create releases yourself, pass the digest your push reported (for example docker buildx build --push prints it, and docker buildx imagetools inspect <image>:<tag> shows what a tag currently resolves to). Ryvn validates the format (sha256: followed by 64 lowercase hex characters) and rejects anything else, including other digest algorithms.

Releases created without a digest keep working exactly as before. Ryvn does not back-fill one by resolving the tag later, because by then the tag might point at different content than the release was built from.

Helm chart artifacts

For Helm chart services, an artifact can also be a published chart. Set type: helm-chart (entries without a type are treated as images) and Ryvn records the chart’s OCI repository, name, version, and digest:

artifacts:
  - name: app
    type: helm-chart
    helmChart:
      repoUrl: oci://ghcr.io/my-org/charts
      chartName: app
      version: "1.2.3"
      digest: "sha256:9a1b…"

ryvn push chart <package> --service <name> -o artifact prints this entry for the chart it just published.

Generating an artifact inventory

A Helm chart usually pulls several container images that are not listed anywhere in your release metadata. ryvn create release-file renders the chart, finds every image reference in the rendered manifests, resolves each image’s digest from its registry, and writes a complete release file you can inspect and then publish:

# Render the chart at the service's configured chart destination
ryvn create release-file my-service 1.2.3 --output-file release.yaml

# Or render a local chart you just published, supplying its chart artifact
ryvn push chart app-1.2.3.tgz --service my-service -o artifact > chart.yaml
ryvn create release-file my-service 1.2.3 \
  --chart app-1.2.3.tgz \
  --artifacts-file chart.yaml \
  --output-file release.yaml

# Publish the inventory
ryvn create release my-service --channel dev -f release.yaml

The generated file names the service and version, lists the chart and every discovered image with its digest, and marks the chart as the primaryArtifact (the artifact whose version is the release version):

service: my-service
version: 1.2.3
primaryArtifact: app
artifacts:
  - name: app
    type: helm-chart
    helmChart:
      repoUrl: oci://ghcr.io/my-org/charts
      chartName: app
      version: "1.2.3"
      digest: "sha256:9a1b…"
  - name: ghcr.io/my-org/my-app
    image:
      repository: ghcr.io/my-org/my-app
      tag: "1.2.3"
      digest: "sha256:4f5c…"
  - name: docker.io/library/redis
    image:
      repository: docker.io/library/redis
      tag: "7.2"
      digest: "sha256:c0ff…"

--chart accepts an oci:// reference, a chart directory, or a packaged .tgz; when omitted, the chart destination configured on the service definition is used. Pass the same values you deploy with (-f values.yaml, --set key=value) so conditional templates render the images you actually run, and --artifacts-file to include artifacts the chart does not reference (for example a chart you published locally). Registry access uses your existing Docker and Helm credentials (docker login, helm registry login, or ryvn create registry-config); public registries need no credentials. An existing <service>-release.ryvn.yaml beside the build can contribute dependencies, migrations, and labels to the generated inventory. It must not define artifacts: the build generates them, and the command fails if it does. create release-file supports Helm chart services only. For web server and job services the inventory is the single image you built, which ryvn describe image <ref> --service <name> -o artifact produces.

Immutable release artifacts

A release file produced by create release-file is an immutable inventory: every artifact carries a digest, and Ryvn rejects the release if any is missing rather than resolving tags later. To get the same guarantee when you assemble the artifacts yourself, pass --inventory:

ryvn describe image ghcr.io/my-org/my-app:1.2.3 --service my-service -o artifact > image.json
ryvn create release my-service 1.2.3 --channel dev --artifacts-file image.json --inventory

Ryvn then requires every artifact to have an OCI repository and digest, and picks the primary artifact automatically when there is exactly one image (web server and job services) or exactly one chart matching the service’s chart destination (Helm services); pass --primary-artifact <name> otherwise. Environments that mirror artifacts into a private registry copy exactly the digests recorded in the inventory before installing the release, so a complete inventory is what makes those mirrors work for images your chart pulls from public registries.

Releases created by ryvn-build-action are immutable inventories automatically: it runs create release-file for Helm chart services, and for container services passes the describe image artifact to create release --inventory.If your chart does not render with its default values or outside a specific namespace, set render_values_files, render_set_values, and render_namespace on the action or the release.yml reusable workflow. They are forwarded to create release-file as -f, --set, and --namespace, and affect only the inventory render.

Creating releases with metadata

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

CLI with File
CLI with 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

# Create release with inline metadata
ryvn create release my-service 1.2.3 \
  --channel dev \
  --channel staging \
  --metadata '{"artifacts":[{"name":"app","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.

Managing container image versions in Helm

When deploying with Helm charts, there are typically two common patterns for versioning and pulling images:

Approach 1: Match image tag with chart version (recommended)

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)

Version range examples

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

Release dependencies say which versions of other services a release works with, and they travel with the release. To order first installs in an environment, or to point a release’s range at one specific installation when a service has several, declare dependencies on the installation instead. See Installation dependencies.

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

Artifact not found

Ensure the artifact repository and tag are accessible from Ryvn’s infrastructure. Check registry credentials and network connectivity.

Dependency resolution failed

Verify that all dependent services exist and are accessible. Check version compatibility and service health.

Metadata validation errors

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 1.2.3 --service my-service -o json

Get started

Agents

Provision

Deploy

Concepts

Configure

Connections

Release

Templating

Observability

Networking

Support

Release Metadata

Overview

File location

Release artifacts

Container image artifacts

Helm chart artifacts

Generating an artifact inventory

Immutable release artifacts

Creating releases with metadata

Approach 1: Match image tag with chart version (recommended)

Approach 2: Decouple chart and image versions

Service dependencies

Dependency types

Version range format

Defining dependencies

Dependency resolution

Migration schemas

Schema version support

Migration schema format

Troubleshooting

Common issues

Debugging metadata

​Overview

​File location

​Release artifacts

​Container image artifacts

​Helm chart artifacts

​Generating an artifact inventory

​Immutable release artifacts

​Creating releases with metadata

​Approach 1: Match image tag with chart version (recommended)

​Approach 2: Decouple chart and image versions

​Service dependencies

​Dependency types

​Version range format

​Defining dependencies

​Dependency resolution

​Migration schemas

​Schema version support

​Migration schema format

​Troubleshooting

​Common issues

​Debugging metadata

Overview

File location

Release artifacts

Container image artifacts

Helm chart artifacts

Generating an artifact inventory

Immutable release artifacts

Creating releases with metadata

Approach 1: Match image tag with chart version (recommended)

Approach 2: Decouple chart and image versions

Service dependencies

Dependency types

Version range format

Defining dependencies

Dependency resolution

Migration schemas

Schema version support

Migration schema format

Troubleshooting

Common issues

Debugging metadata