Skip to main content

Configurations

Configurations let a single workflow version run unchanged across every stage (test, int, e2e, prod). Instead of duplicating a version just to point at a different bucket or replica count per environment, you keep one version definition and bind a different configuration to each stage.

A configuration is a named, flat key/value map (string → string) that belongs to a workflow:

{
  "data": {
    "BUCKET": "prod-bucket",
    "MODEL_PATH": "/models/v3",
    "RAY_REPLICAS": "4"
  }
}

Referencing Configuration Values​

Inside a workflow version, task arguments reference configuration keys with the ${config.KEY} syntax. References are composable within a larger string:

"arguments": {
  "output-bucket": "s3://${config.BUCKET}/${config.MODEL_PATH}/output",
  "worker-replicas": "${config.RAY_REPLICAS}"
}

At run time, every ${config.KEY} pattern is replaced with the resolved value before the workflow is submitted to Argo.

Backward compatible

Workflow versions with no ${config.*} references behave exactly as before. Configurations are entirely optional.

Binding a Configuration to a Stage​

Bind a version and a configuration together on a stage. From then on, runs (and triggers) on that stage need no extra input:

// PUT .../stages/prod
{
  "versionId": "1.0.0",
  "configurationId": "prod-config"
}

A typical setup uses one configuration per environment:

  • stage dev → version 1.0.0 + dev-config (BUCKET=dev-bucket)
  • stage prod → version 1.0.0 + prod-config (BUCKET=prod-bucket)

Resolution Priority​

When a run is created, configuration values are merged per key across up to three sources, highest priority first:

  1. Inline configuration — an ad-hoc key/value map passed in the run request body (one-off tests / overrides).
  2. Inline configurationId — a reference to a saved configuration, passed in the run request body.
  3. Stage-bound configurationId — from the stage assignment (the normal production path).

Because the merge is per key, an inline source can override a single key while the rest fall back to the stage-bound configuration. For example, with prod-config bound to the stage, a run body of { "configuration": { "LOG_LEVEL": "DEBUG" } } overrides only LOG_LEVEL and resolves all other keys from prod-config.

If, after merging, any ${config.KEY} remains unresolved, the run is rejected with 422 Unprocessable Entity listing the missing references.

Triggers

Webhook and schedule triggers always use the stage-bound configuration only — they cannot pass inline configuration.

Audit Snapshot​

Configurations are mutable — updating a configuration replaces its data. To keep history reproducible, every run records the exact values it used in resolvedConfiguration, so you can always see which parameters produced a given run.

Custom Environment Variables​

Configuration keys are not restricted to values that map onto task parameters — you can add extra keys (for example custom environment variables) and reference them from task arguments. Only keys actually referenced by a version's ${config.KEY} patterns must be resolvable; unused keys are simply ignored.

API Reference​

See the CAIP Workflows API Reference for the full configuration CRUD and run endpoints.