Drone provides the ability to expand, or substitute, repository and build metadata to facilitate dynamic pipeline configurations.

• Example commit substitution:

  kind: pipeline
  type: docker
  name: default
  
  steps:
  - name: publish
    image: plugins/docker
    settings:
      tags: ${DRONE_COMMIT}
      repo: octocat/hello-world
  

• Example tag substitution:

  steps:
  - name: publish
    image: plugins/docker
    settings:
      tags: ${DRONE_TAG}
      repo: octocat/hello-world
  

Please see the environment Reference for a list of parameters that can be used for substitution. Please note that some parameters in this list are unavailable for substitution, such as step name, step number, as well as parameters that store statuses and timestamps.

String Operations

Drone provides partial emulation for bash string operations. This can be used to manipulate string values prior to substitution.

• Example variable substitution with substring:

  steps:
  - name: publish
    image: plugins/docker
    settings:
      tags: ${DRONE_COMMIT_SHA:0:8}
      repo: octocat/hello-world
  

• Example variable substitution strips v prefix from v1.0.0:

  steps:
  - name: publish
    image: plugins/docker
    settings:
      tags: ${DRONE_TAG##v}
      repo: octocat/hello-world
  

• Example variable substitution replaces / with -:

  steps:
  - name: publish
    image: plugins/docker
    settings:
      tags: ${DRONE_BRANCH/\//-}
      repo: octocat/hello-world
  

Drone emulates the below string operations. Drone makes a best-effort to emulate these operations however we do not promise perfect emulation.

${parameter^}
${parameter^^}
${parameter,}
${parameter,,}
${parameter:position}
${parameter:position:length}
${parameter#substring}
${parameter##substring}
${parameter%substring}
${parameter%%substring}
${parameter/substring/replacement}
${parameter//substring/replacement}
${parameter/#substring/replacement}
${parameter/%substring/replacement}
${#parameter}
${parameter=default}
${parameter:=default}
${parameter:-default}

Escaping

Parameter expressions are evaluated before the yaml is parsed. If you do not want the system to evaluate an expression it must be escaped.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

kind: pipeline
type: docker
name: default

steps:
- name: build
  commands:
  - echo $GOOS
  - echo $${GOARCH}
  - go build
  - go test

Common Problems

Parameter substitution occurs before the yaml is parsed. If the substitution results in an invalid yaml file you will receive a parsing error:

yaml: unmarshal errors:
cannot unmarshal !!map into string

This can be resolved by quoting parameters to ensure special / reserved characters are escaped:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

kind: pipeline
type: docker
name: default

steps:
- name: notify
  image: plugins/slack
  settings:
    channel: team
    message: "${DRONE_COMMIT}"