> ## Documentation Index
> Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Promotion Pipeline

> Define paths between release channels with manual, timed, or canary criteria to automate how releases move from staging to production.

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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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

```yaml theme={null}
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](#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.

```yaml theme={null}
criteria:
  type: timed
  duration: 4h
```

```yaml theme={null}
# 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.

```yaml theme={null}
filters:
  - resource: environment
    selector:
      name: production
```

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

`string` — required

The type of resource to filter on. Valid values: `environment`

```yaml theme={null}
resource: environment
```

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

`object` — required

Selector to match resources. Fields depend on the resource type.

```yaml theme={null}
selector:
  name: canary-prod
```

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

`string` — optional

Match by resource name (for `environment` resource type).

```yaml theme={null}
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.

```yaml theme={null}
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

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
kind: Service
metadata:
  name: api
spec:
  promotionPipeline: api-pipeline
  ...
```

See the `promotionPipeline` property documentation for your service type:

* [Server](https://ryvn.ai/docs/iac/services/server.md#promotionpipeline)
* [Job](https://ryvn.ai/docs/iac/services/job.md#promotionpipeline)
* [Helm Chart](https://ryvn.ai/docs/iac/services/helm-chart.md#promotionpipeline)
* [Terraform](https://ryvn.ai/docs/iac/services/terraform.md#promotionpipeline)

## 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.

```yaml theme={null}
kind: Blueprint
metadata:
  name: backend-stack
spec:
  promotionPipeline: main-pipeline
  ...
```

See [Blueprint `promotionPipeline` property](https://ryvn.ai/docs/iac/blueprint#promotionpipeline) documentation for more details.

## Examples

### Basic timed pipeline

Automatically promote releases from staging to production after 24 hours:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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
```
