Promotion Pipeline

Promotion pipelines automate and enforce the movement of releases through release channels. They define paths that connect channels and specify criteria that determine when a release is promoted from one channel to another.

# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: PromotionPipeline
metadata:
  name: api-pipeline
spec:
  paths:
    - sourceChannel: staging
      targetChannel: production
      criteria:
        type: manual

Manual promotion

Manual promotion requires explicit user action to promote releases. Use this when you want full control over when releases move between channels.

# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: PromotionPipeline
metadata:
  name: api-pipeline
spec:
  paths:
    - sourceChannel: staging
      targetChannel: production
      criteria:
        type: manual

Timed promotion

Timed promotion automatically promotes releases after they have been in the source channel for a specified duration. Use this for time-based soak testing before promotion.

# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: PromotionPipeline
metadata:
  name: api-pipeline
spec:
  paths:
    - sourceChannel: staging
      targetChannel: production
      criteria:
        type: timed
        duration: 24h

Two details of how the soak is measured:

The clock counts weekday hours only. Time that falls on a Saturday or Sunday is not counted, so a release that enters the source channel on Thursday at 09:00 with a 48h duration becomes eligible on Tuesday at 09:00. Time accrued before a weekend is kept, not reset.
Each release soaks independently. When a newer release lands in the source channel before an older one has finished soaking, the older one keeps its accrued time. Ryvn promotes the newest release that has both finished soaking and is ahead of the target channel, so a channel that receives releases faster than the soak duration still promotes.

Because the newest eligible release wins, a release that is superseded before it finishes soaking may never be promoted: the target channel moves straight to the newer release. Releases are skipped, never promoted out of order — a release the target channel has already moved past is not promoted.

Canary promotion

Canary promotion evaluates installations running the release and promotes when conditions are met. Use this to monitor health of specific installations before promoting to wider availability.

# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: PromotionPipeline
metadata:
  name: api-pipeline
spec:
  paths:
    - sourceChannel: production
      targetChannel: stable
      criteria:
        type: canary
        filters:
          - resource: environment
            selector:
              name: canary-prod
        conditions:
          - type: health
            thresholdPercent: 100
            minHealthDuration: 4h

Properties

`name`

string — required Unique identifier for this promotion pipeline. Used to reference the pipeline from services and blueprints.

name: api-pipeline

`paths`

array — optional List of promotion paths that define how releases flow between channels. Each path connects a source channel to a target channel and specifies promotion criteria.

paths:
  - sourceChannel: staging
    targetChannel: production
    criteria:
      type: timed
      duration: 24h

`paths[].sourceChannel`

string — required Name of the release channel where releases start. When a release is added to this channel, it becomes eligible for promotion according to the path’s criteria.

sourceChannel: staging

`paths[].targetChannel`

string — required Name of the release channel where releases are promoted to. When promotion criteria are met, the release is automatically added to this channel.

targetChannel: production

`paths[].criteria`

object — required Defines when and how releases are promoted from the source channel to the target channel. The criteria type determines what conditions must be met for promotion.

criteria:
  type: manual

`paths[].criteria.type`

string — required Type of promotion criteria. Valid values: manual, timed, canary

manual: Requires explicit promotion trigger via API or UI
timed: Automatically promotes after specified duration
canary: Evaluates source channel installations and promotes when conditions are met

criteria:
  type: timed

`paths[].criteria.duration`

string — required for timed type, optional for canary type Uses Go duration format (e.g., 4h, 24h, 7d). Maximum duration is 31 days.

For timed promotion, the duration a release must remain in the source channel before being promoted. Weekend hours do not count towards it — see Timed promotion.
For canary promotion, an optional minimum bake (soak) window. When set, Ryvn waits for the duration to elapse before evaluating health conditions. When omitted, Ryvn evaluates health conditions immediately.

criteria:
  type: timed
  duration: 4h

# Canary with an optional 1h bake time before health evaluation
criteria:
  type: canary
  duration: 1h
  conditions:
    - type: health
      thresholdPercent: 100
      minHealthDuration: 30m

`paths[].criteria.filters`

array — optional, only valid for canary type Filters that determine which installations are evaluated when checking promotion conditions. Each filter selects installations based on environment characteristics. Only the filtered installations are monitored to determine if conditions are met for promotion to the target channel.

filters:
  - resource: environment
    selector:
      name: production

`paths[].criteria.filters[].resource`

string — required The type of resource to filter on. Valid values: environment

resource: environment

`paths[].criteria.filters[].selector`

object — required Selector to match resources. Fields depend on the resource type.

selector:
  name: canary-prod

`paths[].criteria.filters[].selector.name`

string — optional Match by resource name (for environment resource type).

name: canary-prod

`paths[].criteria.conditions`

array — optional, only valid for canary type Conditions that must be met before promotion occurs. Multiple conditions can be specified, and all must be satisfied.

conditions:
  - type: health
    thresholdPercent: 100
    minHealthDuration: 4h

`paths[].criteria.conditions[].type`

string — required Type of condition to evaluate. Valid values: health

health: Promote when threshold of installations are healthy for the specified duration

type: health

`paths[].criteria.conditions[].thresholdPercent`

integer — optional Percentage of filtered installations that must be healthy. Valid range: 1-100. Either thresholdPercent or thresholdCount must be specified, but not both.

thresholdPercent: 100

`paths[].criteria.conditions[].thresholdCount`

integer — optional Number of filtered installations that must be healthy. Either thresholdPercent or thresholdCount must be specified, but not both.

thresholdCount: 5

`paths[].criteria.conditions[].minHealthDuration`

string — optional Minimum time installations must remain continuously healthy before promotion (e.g., 2h, 24h, 7d). If not specified, promotion occurs as soon as health requirements are met.

minHealthDuration: 4h

Associating with services

To apply a promotion pipeline to a service, set the promotionPipeline property in your service configuration. All releases of that service will follow the pipeline’s promotion paths.

kind: Service
metadata:
  name: api
spec:
  promotionPipeline: api-pipeline
  ...

See the promotionPipeline property documentation for your service type:

Associating with blueprints

To apply a promotion pipeline to a blueprint, set the promotionPipeline property in your blueprint configuration. All releases of that blueprint will follow the pipeline’s promotion paths.

kind: Blueprint
metadata:
  name: backend-stack
spec:
  promotionPipeline: main-pipeline
  ...

See Blueprint promotionPipeline property documentation for more details.

Examples

Basic timed pipeline

Automatically promote releases from staging to production after 24 hours:

kind: PromotionPipeline
metadata:
  name: basic-pipeline
spec:
  paths:
    - sourceChannel: staging
      targetChannel: production
      criteria:
        type: timed
        duration: 24h

Multi-stage pipeline

Chain multiple promotion paths for progressive rollout:

kind: PromotionPipeline
metadata:
  name: multi-stage
spec:
  paths:
    - sourceChannel: dev
      targetChannel: staging
      criteria:
        type: timed
        duration: 4h
    - sourceChannel: staging
      targetChannel: production
      criteria:
        type: timed
        duration: 24h
    - sourceChannel: production
      targetChannel: stable
      criteria:
        type: manual

Canary with health checks

Promote to production channel after monitoring health of installations with canary label:

kind: PromotionPipeline
metadata:
  name: canary-pipeline
spec:
  paths:
    - sourceChannel: staging
      targetChannel: production
      criteria:
        type: canary
        filters:
          - resource: environment
            selector:
              name: canary
        conditions:
          - type: health
            thresholdPercent: 100
            minHealthDuration: 4h

Services

Environments

Installations

Blueprints

Releases

Promotion Pipeline

Manual promotion

Timed promotion

Canary promotion

Properties

`name`

`paths`

`paths[].sourceChannel`

`paths[].targetChannel`

`paths[].criteria`

`paths[].criteria.type`

`paths[].criteria.duration`

`paths[].criteria.filters`

`paths[].criteria.filters[].resource`

`paths[].criteria.filters[].selector`

`paths[].criteria.filters[].selector.name`

`paths[].criteria.conditions`

`paths[].criteria.conditions[].type`

`paths[].criteria.conditions[].thresholdPercent`

`paths[].criteria.conditions[].thresholdCount`

`paths[].criteria.conditions[].minHealthDuration`

Associating with services

Associating with blueprints

Examples

Basic timed pipeline

Multi-stage pipeline

Canary with health checks

​Manual promotion

​Timed promotion

​Canary promotion

​Properties

​name

​paths

​paths[].sourceChannel

​paths[].targetChannel

​paths[].criteria

​paths[].criteria.type

​paths[].criteria.duration

​paths[].criteria.filters

​paths[].criteria.filters[].resource

​paths[].criteria.filters[].selector

​paths[].criteria.filters[].selector.name

​paths[].criteria.conditions

​paths[].criteria.conditions[].type

​paths[].criteria.conditions[].thresholdPercent

​paths[].criteria.conditions[].thresholdCount

​paths[].criteria.conditions[].minHealthDuration

​Associating with services

​Associating with blueprints

​Examples

​Basic timed pipeline

​Multi-stage pipeline

​Canary with health checks

Manual promotion

Timed promotion

Canary promotion

Properties

`name`

`paths`

`paths[].sourceChannel`

`paths[].targetChannel`

`paths[].criteria`

`paths[].criteria.type`

`paths[].criteria.duration`

`paths[].criteria.filters`

`paths[].criteria.filters[].resource`

`paths[].criteria.filters[].selector`

`paths[].criteria.filters[].selector.name`

`paths[].criteria.conditions`

`paths[].criteria.conditions[].type`

`paths[].criteria.conditions[].thresholdPercent`

`paths[].criteria.conditions[].thresholdCount`

`paths[].criteria.conditions[].minHealthDuration`

Associating with services

Associating with blueprints

Examples

Basic timed pipeline

Multi-stage pipeline

Canary with health checks