1.5 Config Basics

Concourse configuration for things like Pipelines and Tasks is done through declarative YAML files.

Concourse configuration supports basic variable substitution by way of ((vars)). There is no built-in support for fancier templating constructs, e.g. loops and conditionals; users are free to use whatever templating system they like.

Table of contents:
  1. 1.5.1 Intro to YAML
    1. 1.5.1.1 YAML Tips & Tricks
    2. 1.5.1.2 YAML Quirks
  2. 1.5.2 Basic Schemas

Intro to YAML

YAML is a human-friendly syntax for writing structured documents. You can think of it as JSON without the sharp edges.

Here's a quick example demonstrating common YAML syntax:

# commented lines are prefixed with the '#' character

# strings
quoted_string: "bar"
unquoted_string: hello world!
multiline_string: |
  hello, world!
  this is one big string with a trailing linebreak!

# arrays
array: [hello, world]
multiline_array:
- hello
- world

# objects
object: {one: uno, two: dos}
multiline_object:
  one: uno
  two: dos

# boolean values
booleans: [true, false]

# numeric values
numeric: [1234, 12.34]

YAML Tips & Tricks

YAML anchor syntax can be used to avoid repetition within configuration.

For example, the following YAML document...:

large_value: &my_anchor
  do_the_thing: true
  with_these_values: [1, 2, 3]

duplicate_value: *my_anchor

...is exactly equivalent to:

large_value:
  do_the_thing: true
  with_these_values: [1, 2, 3]

duplicate_value:
  do_the_thing: true
  with_these_values: [1, 2, 3]

If you find yourself repeating configuration throughout your pipeline, it may be a sign that Concourse is missing some kind of abstraction to make your pipeline less verbose. If you have the time and are interested in helping out with Concourse's design, feedback of this sort is welcome in GitHub Discussions!

YAML Quirks

YAML has some weird parts. For example, all of the following terms are acceptable boolean values: true, false, yes, no, on, off.

YAML is also whitespace-sensitive. For the most part, this is really handy because it keeps you from having to count curly-braces in deeply nested parts of configuration such as job.plan. Sometimes, though, it can be hard to keep track of the correct indentation level.

Basic Schemas

Throughout the Concourse documentation you will come across schema definitions for each API.

The following are basic schema definitions that the other schemas refer to. You can probably skip past this and just make assumptions along the way; this is just here for completeness!

number schema

Any integer, i.e. 1000.

string schema

An arbitrary string value with no content restrictions.

config schema

An arbitrary object representing configuration that is not directly interpreted by Concourse - typically given to a resource type.

uri: https://github.com/vito/booklit
branch: master

All object keys must be strings, preferably snake_cased.

vars schema

An arbitrary object representing key-value definitions for ((vars)).

As with config schema, all object keys must be strings, preferably snake_cased.

env-vars schema

An object containing string keys and string values. Each pair represents an environment variable to set to the given value.

SOME_SIMPLE_VAR: simple-var
SOME_LONG_VAR: |
  This is an example of using YAML multi-line string syntax to set a very
  long environment variable value.
SOME_NUMERIC_VALUE: "1"

Note that in the last example we took special care to quote the number.

boolean schema

true or false.

YAML also supports the alias yes, no, on, or off, but...please don't.

value schema

An arbitrary YAML value. May be a number schema, string schema, boolean schema, config schema, or a [value schema].

values:
- 123
- bar
- true
- key1: abc
  key2: def
- [hello, world]

identifier schema

An identifier is a string value. The following defines the allowed character set for an identifier:

  • Unicode lowercase letters, while still supporting languages that don't have any casing (e.g. Japanese).

  • Decimal numbers.

  • Hyphens - and underscores _ as word separators.

  • Periods . in order to support domain names and version numbers.

The validation rule is as follows:

^[\p{Ll}\p{Lt}\p{Lm}\p{Lo}][\p{Ll}\p{Lt}\p{Lm}\p{Lo}\d\-_.]*$

Where all identifier must start with a Unicode lowercase letter, followed by any number of allowed characters.

Currently, the validation will only show as warnings. For the sake of future-proofing, you may want to conform to it.

dir-path schema

A string value specifying a (typically relative) path of a directory.

file-path schema

A string value specifying a (typically relative) path of a file.

duration schema

A string value in Go time.ParseDuration format. 1h for one hour, 5m for 5 minutes.

version schema

An object with string keys and string values.

The following is an array of versions:

- {"ref": "33042e15e930b6786fc9b0a9ea5dec78689c5e4b"}
- ref: v1.2.0,
  sha: 33042e15e930b6786fc9b0a9ea5dec78689c5e4b
- foo: "0"

Note that in the last example we took special care to quote the number.

In many scenarios where a version can be specified, e.g. get step version, only a subset of the full set of fields is necessary. The latest version matching the fields specified will be chosen.