Variables

In CDS, it is possible to define variables at different levels:

Variable types

Existing variable types:

Placeholder format

All variables in CDS can be invoked using the simple {{.VAR}} format. To simplify the use between all the variable sources, we have defined the following prefixes:

Builtin variables

Here is the list of builtin variables, generated for every build:

The cds.version variable

{{.cds.version}}

CDS version is a builtin variable, it is transmitted through pipelines of a workflow run.

Export a variable inside a step

In a step of type script, you can export a variable as the following:

$ worker export varname thevalue

You can use the build variable in:

See worker export documentation

Shell Environment Variable

All CDS variables, except password type, can be used as plain environment variables.

Theses lines will have the same output

echo '{{.cds.parent.application}}'
echo $CDS_PARENT_APPLICATION

Git variables

Here is the list of git variables:

Here is the list of git variables available only for Bitbucket server

Pipeline parameters

On a pipeline, you can add some parameters, this will let you to use {{.cds.pip.param_name}} in your pipeline.

version: v1.0
name: build

parameters:
  param_name:
    type: string
    default: default_value

stages:
  ...

This will let you to use {{.cds.pip.param_name}} in your pipeline. Then, in the workflow, you can set the value for pipeline parameter in the pipeline context.

name: test-workflow
version: v2.0
workflow:
  the-pipeline:
    pipeline: build
    parameters:
      varname: the-value
...

You can use a Git or Builtin variable. example:

name: test-workflow
version: v2.0
workflow:
  the-pipeline:
    pipeline: build
    parameters:
      varname: {{.cds.version}}
      varname2: {{.cds.pip.param_name}}
...

Notice that you can’t create a pipeline parameter of type password. If you want to use a variable of type password, you have to create it in your project / application or environment. Then, in your workflow, use this variable to set the value of the pipeline parameter - the pipeline parameter can be of type string.

You can also access a pipeline parameter myparam of the pipeline mypipeline from another pipeline in the same workflow using {{.workflow.mypipeline.pip.myparam}}.

Helpers

Some helpers are available to transform the value of a CDS Variable.

Example: run a pipeline, with an application named my_app. A step script:

echo "{{.cds.application | upper}}"

will display

MY_APP

Helpers available and some examples:

Advanced usage

You can use CDS Variables with default helpers:

{{.cds.app.foo | default .cds.app.bar }}

You can use many helpers:

{{.cds.app.foo | upper | lower}}
{{.cds.app.foo | default .cds.app.bar | default .cds.app.biz | upper }}

Deep in code

Are you a Go developer? See all helpers on https://github.com/ovh/cds/blob/v0.54.1/sdk/interpolate/interpolate_helper.go#L23 and some unit tests on https://github.com/ovh/cds/blob/v0.54.1/sdk/interpolate/interpolate_test.go#L72