PrepareJob

The PrepareJob template is a workaround for the limitations of GitHub Actions to handle global variables in GitHub Actions workflows (see actions/runner#480) as well as providing basic string operations (see GitHub Action’s limited set of functions).

The job template generates various output parameters derived from ${{ github }} context.

Features

• Provide branch name or tag name from ${{ github.ref }} variable.

• Check if pipeline is a branch, tag or pull-request pipeline.

• Check if a commit is a merge commit.

• Check if a commit is a release commit.

• Check if a tag is a nightly tag (rolling release tag).

• Check if a tag is a release tag.

• Find associated pull-request (PR) for a merge commit/release commit.

• Provide a version from tag name or pull-request name.

Note

Due to GitHub Action’s broken type system and missing implicit type conversions in YAML files, boolean values need to be returned as string values otherwise type compatibility and comparison are broken. This also requires all inputs to be string parameters, otherwise step’s, job’s or template’s output cannot be assigned to a template’s input.

Problems:

1. Scripts (Bash, Python, …) return results as strings. There is no option or operation provided by GitHub Actions to convert outputs of printf to a boolean in the YAML file.

2. Unlike job template inputs, outputs have no type information. These are all considered string values. Again no implicit or explicit type conversion is provided.

3. While inputs might be defined as boolean and a matching default can be set as a boolean value (e.g., false), a connected variable from ${{ needs }} context will either cause a typing error or a later comparison will not work as expected. Either the comparison works with inputs.param == false for the default value, or it works with a value from ${{ needs }} context, which is a string inputs.param == 'false'.

Behavior

1. Checkout repository.

2. Classify ${{ github.ref }} into branch, tag or pull-request.

3. Compute output parameters.

4. Find associated pull-request.

Job Execution

Dependencies

• GitHub: actions/checkout

• GitHub command line tool ‘gh’

Instantiation

The following instantiation example creates a Prepare job derived from job template PrepareJob version @r6. In a default usecase, no input parameters need to be specified for the job template assuming a main-branch and release-branch called main, a development-branch called dev, as well as semantic versioning for tags and pull-request titles.

jobs:
  Prepare:
    uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r6

  <ReleaseJob>:
    needs:
      - Prepare
    if: needs.Prepare.outputs.is_release_tag == 'true'
    ...
    with:
      version: ${{ needs.Prepare.outputs.version }}

See also

TagReleaseCommit

PrepareJob is usually used to identify if a pipeline’s commit is a merge commit created by a pull-request. If so, this commit can be tagged automatically to trigger a release pipeline (tag pipeline) for the same commit resulting in a full release (PyPI, GitHub Pages, GitHub Release, …).

PublishReleaseNotes

PrepareJob is usually used to identify if a tag pipeline is a release pipeline.

Parameter Summary

Goto input parameters

Parameter Name	Required	Type	Default
ubuntu_image	no	string	'ubuntu-24.04'
main_branch	no	string	'main'
development_branch	no	string	'dev'
release_branch	no	string	'main'
nightly_tag_pattern	no	string	'nightly'
release_tag_pattern	no	string	'(v|r)?[0-9]+(\.[0-9]+){0,2}(-(dev|alpha|beta|rc)([0-9]*))?'

Goto secrets

This job template needs no secrets.

Goto output parameters

Result Name	Type	Description
on_main_branch	string
on_dev_branch	string
on_release_branch	string
is_regular_commit	string
is_merge_commit	string
is_release_commit	string
is_nightly_tag	string
is_release_tag	string
ref_kind	string
branch	string
tag	string
version	string
pr_title	string
pr_number	string

Input Parameters

ubuntu_image

Type:

string

Required:

no

Default Value:

'ubuntu-24.04'

Possible Values:

See actions/runner-images - Available Images for available Ubuntu image versions.

Description:

Name of the Ubuntu image used to run this job.

main_branch

Type:

string

Required:

no

Default Value:

'main'

Possible Values:

Any valid branch name.

Description:

Name of the main branch.

development_branch

Type:

string

Required:

no

Default Value:

'dev'

Possible Values:

Any valid branch name.

Description:

Name of the development branch.

release_branch

Type:

string

Required:

no

Default Value:

'main'

Possible Values:

Any valid branch name.

Description:

Name of the branch containing releases.

nightly_tag_pattern

Type:

string

Required:

no

Default Value:

'nightly'

Possible Values:

Any valid regular expression.
Suggested alternative values: latest, rolling

Description:

Name of the tag used for rolling releases, a.k.a nightly builds.

release_tag_pattern

Type:

string

Required:

no

Default Value:

'(v|r)?[0-9]+(\.[0-9]+){0,2}(-(dev|alpha|beta|rc)([0-9]*))?'

Possible Values:

Any valid regular expression.

Description:

A regular expression describing a pattern for identifying a release tag.

The default pattern matches on a semantic version number separated by dots. It supports up to 3 digit groups. It accepts an optional v or r prefix. Optionally, a postfix of dev, alpha, beta or rc separated by a hyphen can be appended. If needed, the postfix can have a digit group.

Matching tag names as releases:

• v1, r1

• 1, 1.1, 1.1.1

• v1.2.8-dev

• v3.13.5-alpha2

• v4.7.22-beta3

• v10.2-rc1

Secrets

This job template needs no secrets.

Outputs

on_main_branch

Type:

string

Default Value:

'false'

Possible Values:

'true', 'false'

Description:

Returns 'true' if the pipeline’s commit is on main branch, otherwise return 'false'.

on_dev_branch

Type:

string

Default Value:

'false'

Possible Values:

'true', 'false'

Description:

Returns 'true' if the pipeline’s commit is on development branch, otherwise return 'false'.

on_release_branch

Type:

string

Default Value:

'false'

Possible Values:

'true', 'false'

Description:

Returns 'true' if the pipeline’s commit is on release branch, otherwise return 'false'.

is_regular_commit

Type:

string

Default Value:

'false'

Possible Values:

'true', 'false'

Description:

Returns 'true' if the pipeline’s commit is not a merge commit nor release commit, otherwise return 'false'.

is_merge_commit

Type:

string

Default Value:

'false'

Possible Values:

'true', 'false'

Description:

Returns 'true' if the pipeline’s commit is on main branch or development branch and has more than one parent (merge commit), otherwise return 'false'.

is_release_commit

Type:

string

Default Value:

'false'

Possible Values:

'true', 'false'

Description:

Returns 'true' if the pipeline’s commit is on release branch and has more than one parent (merge commit), otherwise return 'false'.

is_nightly_tag

Type:

string

Default Value:

'false'

Possible Values:

'true', 'false'

Description:

Returns 'true' if the pipeline is a tag pipeline for a commit on release branch and the tag’s name matches the nightly tag pattern, otherwise return 'false'.

is_release_tag

Type:

string

Default Value:

'false'

Possible Values:

'true', 'false'

Description:

Returns 'true' if the pipeline is a tag pipeline for a commit on release branch and the tag’s name matches the release tag pattern, otherwise return 'false'.

ref_kind

Type:

string

Default Value:

'unknown'

Possible Values:

'branch', 'tag', 'pullrequest', 'unknown'

Description:

Returns 'branch' if pipeline’s commit is on a branch or returns 'tag' if the pipeline runs for a tagged commit, otherwise returns 'unknown' in case of an internal error.

If the kind is a branch, the branch name is available in the job’s branch result.
If the kind is a tag, the tags name is available in the job’s tag result.
If the kind is a pull-request, the pull request’s id is available in the job’s pr_number result.
Moreover, if the tag matches the release_tag_pattern, the extracted version is available in the job’s version result.

Note

GitHub doesn’t provide standalone branch or tag information, but provides the variable ${{ github.ref }} specifying the currently active reference (branch, tag, pull, …). This job template parses the context’s variable and derives if a pipeline runs for a commit on a branch or a tagged commit.

branch

Type:

string

Default Value:

''

Possible Values:

Any valid branch name.

Description:

Returns the branch’s name the pipeline’s commit is associated to, if ref_kind is 'branch', otherwise returns an empty string ''.

tag

Type:

string

Default Value:

''

Possible Values:

Any valid tag name.

Description:

Returns the tag’s name the pipeline’s commit is associated to, if ref_kind is 'tag', otherwise returns an empty string ''.

version

Type:

string

Default Value:

''

Possible Values:

Any valid version matching release_tag_pattern.

Description:

In case the pipeline runs for a tag, it returns the tag’s name, if the name matches release_tag_pattern, otherwise returns an empty string ''.
In case the pipeline runs for a branch, then the commit is checked if it’s a merge commit and corresponding pull-request (PR) is searched. When a matching PR can be located and it’s title matches release_tag_pattern, then this title is returned as a version, otherwise it returns an empty string ''.

pr_title

Type:

string

Default Value:

''

Possible Values:

'true', 'false'

Description:

Returns the associated pull-request’s title, if the pipeline’s commit is a merge commit and the located pull-request’s title for this commit matches release_tag_pattern, otherwise returns an empty string ''.

pr_number

Type:

string

Default Value:

''

Possible Values:

'true', 'false'

Description:

Returns the associated pull-request’s number, if the pipeline’s commit is a merge commit and the located pull-request’s title for this commit matches release_tag_pattern, otherwise returns an empty string ''.

Optimizations

This template offers no optimizations (reduced job runtime).