release Trait

Attributes

name	required?	default	type	explanation
assets	no	[]	List[concourse.model.traits.release.BuildstepLogAsset | concourse.model.traits.release.BuildstepFileAsset]	additional release-assets to publish.
nextversion	no	bump_minor	NextVersion	specifies how the next development version is to be calculated
release_callback	no	None	str	an optional callback that is called during release commit creation. The callback is passed the absolute path to the main repository’s work tree via environment variable REPO_DIR. Any changes left inside the worktree are added to the resulting release commit.
release_callback_image_reference	no	None	OciImageCfg	if specified, the release_callback will be run in a virtualisation container using the chosen container image (if not specified, the callback is run as a subprocess)
rebase_before_release	no	False	bool	whether or not a rebase against latest branch head should be done before publishing release commits.
next_version_callback	no	None	str	an optional callback that is called during next version commit creation. The callback is passed the absolute path to the main repository’s work tree via environment variable REPO_DIR. Any changes left inside the worktree are added to the commit bumping the version immediately after the release-commit.
release_notes_policy	no	default	ReleaseNotesPolicy	configures the release notes handling policy
release_commit_publishing_policy	no	push_to_branch	ReleaseCommitPublishingPolicy	configures how the release commit should be published
commit_message_prefix	no	None	str	an optional prefix for release commit messages
next_version_commit_message_prefix	no	None	str	an optional prefix for the commit message of the commit bumping the release version immediately after the release-commit
merge_release_to_default_branch_commit_message_prefix	no	None	str	an optional prefix for the merge-commit message when merging back release-commit from tag to default branch
git_tags	no	- ref_template: refs/tags/{VERSION}	list	a list of tags to tag the release commit with, at least one. The following placeholders are available: {VERSION}: The version to be released (i.e. the ‘effective version’) The first tag will be used to create the GitHub-release.
release_on_github	no	True	bool	if true, a github release is published.
on_tag_conflict	no	ignore	TagConflictAction	specifies the action to take if the tag to be pushed (refs/tags/<effective-version>) already exists (relevant, if release_on_github is not set to False). Such cases can occur if pushing of “bump-commit” after previous release failed. Default value is chosen for backwards-compatibility. fail will lead to the version step to fail (which will shorten the time to discover this error, and thus save time) increment-patch-version will increment effective version’s patchlevel (and thus avoid a conflict)

assets[] (BuildstepLogAsset) Attributes

name	required?	default	type	explanation
ocm_labels	yes	None	List[Dict[str, object]]
type	no	build-step-log	str
name	no	None	str
step_name	yes	None	str
artefact_type	no	text/plain	str
artefact_extra_id	yes	None	Dict[str, str]
purposes	yes	None	List[str]
comment	no	None	str | None
github_asset_name	no	None	str | None

assets[] (BuildstepFileAsset) Attributes

name	required?	default	type	explanation
ocm_labels	yes	None	List[Dict[str, object]]
type	no	build-step-file	str
name	no	None	str
step_name	yes	None	str
artefact_type	no	application/data	str
artefact_extra_id	yes	None	Dict[str, str]
purposes	yes	None	List[str]
comment	no	None	str | None
github_asset_name	no	None	str | None
step_output_dir	yes	None	str
path	yes	None	str
prefix	no	None	str | None
mode	no	tar	FileAssetMode

nextversion Enumeration Values

value	explanation
bump_major	Increments the major version of the next development cycle
bump_minor	Increments the minor version of the next development cycle
bump_patch	Increments the patch version of the next development cycle
noop	No change to the next development cycle version done

release_callback_image_reference (OciImageCfg) Attributes

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

release_notes_policy Enumeration Values

value	explanation
default	Create release notes and add them to the GitHub release.
disabled	Do not create release notes.

release_commit_publishing_policy Enumeration Values

value	explanation
push_to_branch	publish release tag to branch
tag_only	publish release tag to dead-end
tag_and_merge_back	publish release tag to dead-end and merge back release commit to default branch
skip	neither create, nor publish either of release- and bump-commits

on_tag_conflict Enumeration Values

• ignore

• fail

• increment-patch-version

Dependencies

This trait requires the following traits to be declared:

• component_descriptor trait

• version trait

This trait add release job semantics to the declaring build job.

Note

while not enforced, it is strongly recommended to configure the effective version operation to finalize (see version Trait)

The following operations are performed:

• create a release commit (persisting effective version + optional changes from callback)

• push and tag said commit as refs/tags/<effective_version>

• create a GitHub release for said tag

  • add Component Descriptor if present

• calculate next development version and persist it (“bump commit”)

• post release notes to slack if Slack trait is declared

Note

Declaring this trait changes the default triggering behaviour to “manual”

Optional Release Callback

If an optional release-callback is specified, the release commit (if created) can be enriched with custom diffs (e.g. to update a build-tool-specific dependency declarations file).

Contract

• non-zero exit codes are considered as an error (leads to release failure)

• the following environment variables are passed: - REPO_DIR: absolute path to main repository - EFFECTIVE_VERSION: the effective version (see version Trait)

Example

traits:
  version:
    preprocess: 'finalize' # recommended
  release:
    nextversion: 'bump_minor'
    release_callback: 'release_callback' # relative to main repository root

Optional Dev Cycle Callback

If an optional dev-cycle-callback is specified, the dev-cycle commit (if created) can be enriched with custom diffs (e.g. to update a build-tool-specific dependency declarations file).

Contract

• non-zero exit codes are considered as an error (leads to release failure)

• the following environment variables are passed: - REPO_DIR: absolute path to main repository - EFFECTIVE_VERSION: the effective version (see version Trait)

Example

traits:
  version:
    preprocess: 'finalize' # recommended
  release:
    nextversion: 'bump_minor'
    dev_cycle_callback: 'dev_cycle_callback' # relative to main repository root