Skip to main content
Releases can include metadata about artifacts (container images), dependencies (required services), and migrations (database schema changes). This metadata is defined in a {service-name}-release.ryvn.yaml file that the Ryvn CLI reads when creating releases.
Unlike other Ryvn resource types (Service, Environment, ServiceInstallation), release metadata files do not use the kind/metadata.name envelope. The file contains only the release content fields (artifacts, dependencies, migrations) and the service and version are inferred from the filename and CLI arguments.
# Example: my-app-release.ryvn.yaml
artifacts:
  - name: api
    image:
      repository: ghcr.io/my-org/api
      tag: "1.0.0"

dependencies:
  - service: database
    minVersion: "1.0.0"
    maxVersion: "2.x.x"
    optional: false

migrations:
  - version: 1
    name: "initial schema"
  - version: 2

​
Specify Artifacts

Artifacts define the container images associated with a release. 
artifacts:
  - name: api
    image:
      repository: ghcr.io/acme/api
      tag: "1.0.0"
Multiple artifacts: 
artifacts:
  - name: api
    image:
      repository: ghcr.io/acme/api
      tag: "2.0.0"

  - name: worker
    image:
      repository: ghcr.io/acme/worker
      tag: "2.0.0"

  - name: migrator
    image:
      repository: ghcr.io/acme/migrator
      tag: "2.0.0"

​
Specify Dependencies

Dependencies specify other services required for this service to function. 
dependencies:
  - service: database
    minVersion: "1.0.0"
    maxVersion: "2.x.x"
    optional: false
Multiple dependencies with optional: 
dependencies:
  - service: postgres
    minVersion: "14.0.0"
    maxVersion: "15.x.x"
    optional: false

  - service: redis
    minVersion: "7.x.x"
    optional: false

  - service: elasticsearch
    minVersion: "8.x.x"
    optional: true
Version constraints support wildcards:
  • 1.2.3 - Exact version
  • 1.2.x - Any patch version of 1.2
  • 1.x.x - Any minor/patch version of 1
  • 0.x.x - Any version in the 0.x series

​
Specify Migrations

Migrations track database schema changes associated with a release. Migrations block (version required, name optional): 
migrations:
  - version: 1
    name: "create base tables"
  - version: 2
  - version: 3
    name: "add indexes"

​
Properties

​
artifacts[].name

string — required Identifier for the artifact (e.g., “api”, “worker”, “migrator”). Must be unique within a release. 
name: api

​
artifacts[].image.repository

string — required Full image repository URL including registry path. 
image:
  repository: ghcr.io/acme/api

​
artifacts[].image.tag

string — required Image tag, typically the release version. 
image:
  tag: "1.0.0"

​
dependencies[].service

string — required Name of the required service. 
service: database

​
dependencies[].minVersion

string — optional Minimum required version. Supports wildcards. 
minVersion: "1.0.0"

​
dependencies[].maxVersion

string — optional Maximum allowed version. Supports wildcards. 
maxVersion: "2.x.x"

​
dependencies[].optional

boolean — required Whether the dependency is optional. Required dependencies block deployment if missing. 
optional: false

​
migrations[].version

integer — required Migration version number. Must be a non-negative integer. 
version: 1

​
migrations[].name

string — optional Optional name for the migration (max 120 characters). Provides context about what the migration does. 
name: "add users table"

​
Examples

Basic service with single artifact: 
artifacts:
  - name: api
    image:
      repository: ghcr.io/acme/api
      tag: "1.0.0"
Service with dependencies: 
artifacts:
  - name: user-service
    image:
      repository: ghcr.io/acme/user-service
      tag: "2.0.0"

dependencies:
  - service: auth-service
    minVersion: "1.0.0"
    maxVersion: "2.x.x"
    optional: false

  - service: notification-service
    minVersion: "1.x.x"
    optional: true

migrations:
  - version: 5
    name: "add user preferences table"
Multi-artifact service: 
artifacts:
  - name: ingestor
    image:
      repository: ghcr.io/acme/ingestor
      tag: "3.0.0"

  - name: processor
    image:
      repository: ghcr.io/acme/processor
      tag: "3.0.0"

  - name: exporter
    image:
      repository: ghcr.io/acme/exporter
      tag: "3.0.0"

dependencies:
  - service: message-queue
    minVersion: "2.0.0"
    maxVersion: "3.x.x"
    optional: false

  - service: storage-service
    minVersion: "1.x.x"
    optional: false

migrations:
  - version: 10
    name: "create processing_jobs table"
  - version: 11
    name: "add indexes for export queries"
  - version: 12