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.
-
1.5.1
Intro to YAML
- 1.5.1.1 YAML Tips & Tricks
- 1.5.1.2 YAML Quirks
- 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
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!
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: masterAll 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.
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.
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.
powered by