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

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

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

on_tag_conflict Enumeration Values

  • ignore

  • fail

  • increment-patch-version

Dependencies

This trait requires the following traits to be declared:

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

  • 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