Pipeline Definition

Any GitHub repository residing below an organisation owned by the Gardener team is scanned for .ci/pipeline_definitions files within their default branch’s source tree. If a valid pipeline definition is found, all contained pipeline definitions are generated into concourse build pipelines.

Pipeline definitions are valid YAML files adhering to the schema defined in this reference documentation.

Pipeline Definition Schema

Pipeline definition documents may contain an arbitrary amount of pipelines. Each top-level attribute in a .ci/pipeline_definitions file declares a pipeline. The attribute name being the pipeline name.

Danger

All pipeline names share a global namespace. So be sure not to re-use an existing name already in use be another component.

Attributes

attribute	explanation
<name>	the user-chosen pipeline name. Top-level attribute
render_pipeline	optional flag to disable rendering of the current pipeline
template	pipeline template to use. Defaults to ‘default’ (for future extensions)
base_definition	inherited from all Jobs
jobs	defines Jobs

Note

Each pipeline should at least define one job. Otherwise it would be empty.

Note

Pipeline names are displayed in the Concourse UI. Try to keep names reasonably short (< 20 chars) and refrain from using whitespace of non-ASCII charaters.

Example `.ci/pipeline_definitions`

define a build pipeline named my_pipeline
define two Build Jobs job_A, job_B

my_pipeline:
  render_pipeline: True # default value - may be omitted
  template: 'default'   # default value - may be omitted
  base_definition:
    ... # same schema as for jobs applies
  jobs:
    job_A:
      ... # see pipeline jobs definition for schema
    job_B: ~

Example - Inheritance / “base_definition”

define a common build step “inherit_me”
define two jobs inheriting it

another_pipeline:
  base_definition:
    steps:
      inherit_me: ~

  jobs:
    job_a:
      steps:
        another_step:
          depends: ['inherit_me']
    job_b: ~

Result

job_a has two steps: inherit_me (from base_definition) and another_step
job_b has one step: inherit_me

Branch-specific configuration

By default, only the default branch is considered. An optional branch.cfg YAML file may be placed in a repository’s special ref refs/meta/ci.

If a branch configuration is present in a repository, then different semantics is applied when searching the repository for pipeline definitions:

For each branch, a matching branch configuration element is looked up. Iff a matching element is found, the pipeline definition file (if present) from that branch’s head’s worktree is used to instantiate the defined pipelines. Branch-specific pipeline definition fragments (see inherit attribute) are optionally applied.

A common usage scenario may be the declaration of hotfix release jobs for release branches.

Attributes

attribute	explanation
cfgs	mandatory root attribute
<cfg_name>	user-chosen configuration element name (ASCII-alphanumeric)
branches	list of regular expressions used to match branche names (at least one)
inherit	optional pipeline definition fragment; inherited into pipeline definition

Example (schematic)

cfgs:         # root attribute, required
   <cfg_name>:
        branches: # branch filter
           <list of branch names>
        inherit: ~ # optional branch-specific pipeline definition

Example (hotfix-branch release jobs)

cfgs:
    default:
        branches: ['master']
        inherit:
            example-pipeline:
                jobs:
                    release-job:
                        traits:
                            release:
                                nextversion: 'bump_minor'
    hotfix:
        branches: ['hotfix-.*']
        inherit:
            example-pipeline:
                jobs:
                    release-job:
                        traits:
                            release:
                                nextversion: 'bump_patch'

Pipeline Definition