Skip to main content
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

​
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 Duration that a release must remain in the source channel before being promoted. Uses Go duration format (e.g., 4h, 24h, 7d). Maximum duration is 31 days. 
criteria:
  type: timed
  duration: 4h

​
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