Substitution

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. Only parameters in this list can be used for substitution.

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
    

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}"