update_component_deps Trait

Attributes

name	required?	default	type	explanation
set_dependency_version_script	no	.ci/set_dependency_version	str	configures the path to set_dependency_version script
set_dependency_version_script_container_image	no	None	OciImageCfg	if specified, the set_dependency_version_script will be executed in a separate OCI container using the specified container image. main_repository will be mounted at /mnt/main_repo
upstream_component_name	no	None	str	configures the upstream component
upstream_update_policy	no	strictly_follow	str	configures the upstream component update policy
merge_policy	no	None	MergePolicy	whether or not created PRs should be automatically merged. deprecated
merge_policies	no	()	List[MergePolicyConfig]	merge policies to apply to detected component upgrades. By default, upgrade pull-requests must be merged manually
after_merge_callback	no	None	str	callback to be invoked after auto-merge
ignore_prerelease_versions	no	True	bool	ignores prerelease versions like “0.1.0-dev-abc” and only creates upgrade pr’s for finalized versions.
vars	no	{}	dict	env vars to pass to after_merge_callback (similar to step’s vars)

set_dependency_version_script_container_image (OciImageCfg) Attributes

name	required?	default	type	explanation
image_reference	yes	None	str	the OCI Image reference to use

merge_policy Enumeration Values

• manual

• auto_merge

merge_policies (MergePolicyConfig) Attributes

name	required?	default	type	explanation
component_names	no	[]	List[str]	a sequence of regular expressions. This merge policy will be applied to matching component names. Matches all component names by default
merge_mode	no	manual	MergePolicy	whether or not created PRs should be automatically merged
merge_method	no	merge	MergeMethod	The method to use when merging PRs automatically. For more details, check the GitHub documentation for merge-methods.

merge_policies.merge_mode Enumeration Values

• manual

• auto_merge

merge_policies.merge_method Enumeration Values

• merge

• rebase

• squash

Dependencies

This trait requires the following traits to be declared:

• component_descriptor trait

Declaring jobs receive “Component Dependencies upgrade” semantics. Upon execution, any immediate dependencies declared in the component’s Component Descriptor will be checked for newer released versions (compared to the ones declared in the current component descriptor). Checking for newer versions is done using semver semantics.

For each discovered component with a later release version, an Upgrade Pull Request is created to the greates discovered component version. Outdated Upgrade Pull Requests are removed.

Note

automatically created Upgrade PRs are identified using the following naming convention:

[ci:<dependency-type>:<dependency-name>:<current-version>-><target-version>]

Component Upgrade Contract

Declaring components must offer an executable at .ci/set_dependency_version in their repositories. It is called by the update component dependencies job for each discovered dependency upon pull request creation.

The executable must modify the indicated component work tree such a (component-specific) way that the changes contain the required changes for the requested dependency upgrade.

The execution environment is defined to be the latest version of cc-job-image. In this environment it may be assumed that a Python3 runtime is available, along with all tools from github.com/gardener/cc-utils (available from PYTHONPATH).

Passed Environment Variables

name	explanation
DEPENDENCY_TYPE	one of: ‘component’, ‘container_image’, ‘web’, ‘generic’
DEPENDENCY_NAME	the dependency name as declared in component descriptor
LOCAL_DEPENDENCY_NAME	the logical name of the dependency within the component descriptor
DEPENDENCY_VERSION	the discovered target component version (e.g. 1.2.3)
REPO_DIR	the absolute path to component repo work tree

Behavioural Contract

The executable must return an exit code equal to zero iff all environment variables as described above were set to sane values. I.e. an unknown dependency type or name must be signalled as an error (exit code != zero).

The executable should output reasonable error descriptions in case of invalid or insane arguments.

The work tree specified via REPO_DIR may be assumed to be “clean” and writeable.

Extension Note

This contract is also intended to be extended for other dependency types. Therefore, implementations of .ci/set_dependency_version are recommended to be implemented such as to reject dependency types other than ‘component’ to avoid undefined behaviour.