Pipeline Job

Each Build Pipeline may define an arbitrary amount of build jobs. Job definitions reside below a pipeline’s jobs attribute. Each job defines their name as root element.

Attributes

attribute

explanation

<name>

the user-chosen job name.

repo

main repository configuration

repos

optionally defines additional repositories

steps

defines Build Steps

traits

defines Traits

(GitHub) Repositories

Main Repository

Each pipeline has a main repository. It is implied by the GitHub repository from which the pipeline definition was read.

  • logical repository name defaults to source

  • branch and repo_path are determined by repository

  • repository path is implied by repository

Additional Repositories

Additional repositories may be referenced. Different from the main repository, all of the following attributes must be specified:

  • logical repository name

  • branch name

  • repository path

Repository Attributes

Attributes

name

required?

default

type

explanation

name

no

source

str

the logical repository name. affects environment variable names and is used to reference from traits.

cfg_name

no

None

str

the github_cfg to use for authentication. Defaults to concourse-specific default

force_push

no

False

bool

whether or not force-pushes ought to be done

trigger_paths

no

exclude: []
include: []

dict

repository paths to either ignore or to restrict triggering to

trigger

no

None

bool

overwrites the defaults for triggering behaviour

disable_ci_skip

no

False

bool

whether to disable the ignoring of commits with [ci skip] in commit msg

branch

no

None

str

only for non-main repository: specify branch to work with

path

no

None

str

github repository path (e.g. gardener/gardener)

hostname

no

None

str

do not use

preferred_protocol

no

None

Protocol

optionally overwrites the preferred protocol to use

source_labels

no

[]

List[Label]

labels to add to the corresponding source declaration in base-component-descriptor

submodule_cfg_names

no

[]

List[str]

The name of github configs to provide for authentication of submodules which are not stored on the same git server as the repository. The config used by the repository itself is included by default. The configs given must support http-auth, otherwise they will be omitted.

preferred_protocol Enumeration Values

  • ssh

  • https

source_labels[] (Label) Attributes

name

required?

default

type

explanation

name

yes

None

str

value

yes

None

str | int | float | bool | dict | list

Default behaviour for trigger attribute

The trigger attribute specifies whether or not head updates should trigger a job execution.

If it is not explicitly configured, the default behaviour is defined as follows:

  • additional repositories default to false

  • main repository:

    • presence of release or cronjob trait –> false

    • presence of pull-request trait –> true

    • if none of the above traits are present –> true

trigger_paths attribute

Allows to restrict build triggering by repository changes. If trigger attribute evaluates to false, this attribute has no effect.

Using trigger_paths, it is possible to ignore updates in case they touch (or do not touch) certain repository paths (globbing syntax supported).

  • include: only react on specified paths - ignore all others

  • exclude: ignore changes to specified paths (inverse of include)

cfg_names attribute

Specifies the GitHub instance hosting the repository. For each Concourse instance, there is a default GitHub instance that is used in case no cfg_name is specified.

Available configurations are stored in a private configuration repository (kubernetes/cc-config).

Valid cfg_names are: - github_com - github_wdf_sap_corp

Examples
  • reference an additional repository github.com/foo/bar, name it my_repo

  • the repository will be made available to builds at ${MY_REPO_PATH}

repos:
- name: 'my_repo'
  path: 'foo/bar'
  branch: 'master'    # must be specified - does not default to master
  cfg_name: 'github_com'

Environment Variables

Depending on pipeline definition, build jobs are run with a set of environment variables. The variables that are defined depend on:

  • which repositories are defined (and their logical names)

  • which traits are defined

In case user-specified identifiers are used as input to construct environment variable names, those are converted to UPPER-case. Kebap-case is converted into snake-case (or in other words: any occurrence of dash - characters are converted to underscore _ characters).

Note

For non-ASCII or non-alphanumeric characters, the behaviour is undefined. Usage of those characters is forbidden for user-defined identifiers.

Environment Variables from repositories

For each repository, the following environment variable set is defined:

  • <NAME>_PATH -> relative path to repository’s work tree

  • <NAME>_BRANCH -> the configured branch

  • <NAME>_GITHUB_REPO_OWNER_AND_NAME -> github_path (e.g. gardener/gardener)

In addition, the relative path to the main repository is always stored in the MAIN_REPO_DIR env variable.

Example

In case the main repository has not been explicitly configured with a name, its default logical name is source. Therefore, the following environment variables will then be defined:

  • SOURCE_PATH

  • SOURCE_BRANCH

  • SOURCE_GITHUB_REPO_OWNER_AND_NAME

  • MAIN_REPO_DIR