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

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