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.

• Decide from a list of conditions on the ref whether GitHub Pages are published.

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. Delay job execution by pipeline-delay seconds.

2. Checkout repository.

3. Dump the ${{ github }} context into the job log.

4. Classify ${{ github.ref }} into branch, tag or pull-request and compute all output parameters (main_branch, development_branch, release_branch, nightly_tag_pattern, release_tag_pattern).

5. Evaluate publish_pages_on into publish_pages.

6. Find the associated pull-request.

   Runs for release commits only - a merge commit on the main-branch or a version-branch. A merge commit on the development-branch originates from a pull-request based on the development-branch, which is not a release.

   Merged pull-requests are searched by the merge commit’s second parent, then reduced to those whose headRefOid equals it, because the second parent of a merge commit is the head commit of the merged branch. The search alone would also list pull-requests that merely contain that commit. If a pull-request was closed and recreated from the same branch, both share a head commit and the most recently merged one is used.

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 @r8. 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@r8

  <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-26.04'
pipeline-delay	no	number	0
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]*))?'
prerelease_tag_pattern	no	string	'(v|r)?[0-9]+(\.[0-9]+){0,2}-(dev|alpha|beta|rc)([0-9]*)'
publish_pages_on	no	string	four conditions - see description

Goto secrets

This job template needs no secrets.

Goto output parameters

Result Name	Type	Description
on_default_branch	string	Pipeline runs on the repository’s default branch.
on_main_branch	string	Pipeline runs on the main branch.
on_release_branch	string	Pipeline runs on the main branch or a version branch.
on_dev_branch	string	Pipeline runs on the development branch.
is_regular_commit	string	The commit is neither a merge commit nor a release commit.
is_merge_commit	string	The commit has more than one parent.
is_release_commit	string	The commit is a merge commit on the main branch or a version branch.
is_nightly_tag	string	The tag matches the nightly tag pattern.
is_release_tag	string	The tag matches the release tag pattern.
has_submodules	string	The repository contains Git submodules - see the note on that output.
ref_kind	string	'branch', 'tag' or 'pull-request'.
default_branch	string	Name of the repository’s default branch.
branch	string	Branch name, if the pipeline runs on a branch.
tag	string	Tag name, if the pipeline runs on a tag.
version	string	Version derived from the tag or the pull-request title.
is_prerelease	string	The version matches the pre-release tag pattern.
pr_title	string	Title of the associated merged pull-request.
pr_number	string	Number of the associated merged pull-request.
git_submodule_count	string	Number of registered Git submodules.
git_submodule_names	string	Names of the registered Git submodules.
git_submodule_paths	string	Paths of the registered Git submodules.
publish_pages	string	The ref matches a condition of publish_pages_on.

Input Parameters

ubuntu_image

Type:

string

Required:

no

Default Value:

'ubuntu-26.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.

pipeline-delay

Type:

number

Required:

no

Default Value:

0

Possible Values:

Any non-negative number of seconds. 0 disables the delay.

Description:

Delay this job’s start by the given number of seconds.
GitHub Actions starts all jobs without dependencies at once. Delaying the pipeline’s first job lets GitHub allocate runners for the remaining jobs before this one occupies a runner slot.

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

prerelease_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 which versions are pre-releases, checked against version. The result is is_prerelease.

The default pattern is release_tag_pattern’s with a mandatory postfix: v10.0.0-rc1, v1.2.8-dev and v3.13.5-alpha2 are pre-releases, v10.0.0 isn’t.

publish_pages_on

Type:

string

Required:

no

Default Value:

default-branch, development-branch, release-tag and nightly-tag, one per line.

Possible Values:

A newline separated list of the conditions below. Empty lines and lines starting with # are ignored.

Description:

Conditions on the pipeline’s ref under which publish_pages returns 'true'. The conditions are or-ed, so one matching condition is sufficient. An unknown condition or an invalid regular expression fails the job on every pipeline, not only on those that would publish.

default-branch:

The pipeline runs on the repository’s default branch.

main-branch:

The pipeline runs on main_branch.

development-branch:

The pipeline runs on development_branch.

release-branch:

The pipeline runs on release_branch.

release-tag:

The tag matches release_tag_pattern.

nightly-tag:

The tag matches nightly_tag_pattern.

branch=<regexp>:

The branch name matches <regexp>.

tag=<regexp>:

The tag name matches <regexp>.

<regexp> is a POSIX extended regular expression, as evaluated by Bash’s =~ operator, and is anchored at both ends. Character class shortcuts like \d are not supported, use [0-9] instead.
A pull-request pipeline matches no condition.

Example:

publish_pages_on: |
  default-branch
  release-tag
  branch=release/[0-9]+\.[0-9]+

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

is_prerelease

Type:

string

Possible Values:

'true', 'false'

Description:

Returns 'true', if version matches prerelease_tag_pattern, e.g. v10.0.0-rc1, otherwise 'false' - also when there is no version.
CompletePipeline publishes such a release page as a pre-release, which doesn’t become the repository’s latest release.

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

default_branch

Type:

string

Possible Values:

The repository’s default branch name, e.g. 'main' or 'dev'.

Description:

Name of the repository’s default branch as reported by the GitHub API.

on_default_branch

Type:

string

Possible Values:

'true' / 'false'

Description:

The pipeline runs on the repository’s default branch.
This is not necessarily the release branch - repositories using a dev/main split have their default branch set to dev.

has_submodules

Type:

string

Possible Values:

'true' / 'false'

Description:

The repository contains a .gitmodules file.

git_submodule_count

Type:

string

Possible Values:

A non-negative integer as string.

Description:

Number of Git submodules registered in the repository.

git_submodule_names

Type:

string

Possible Values:

A colon separated list of submodule names, e.g. 'libA:libB'.

Description:

Names of the Git submodules registered in the repository.

git_submodule_paths

Type:

string

Possible Values:

A colon separated list of paths, e.g. 'deps/libA:deps/libB'.

Description:

Paths of the Git submodules registered in the repository.

publish_pages

Type:

string

Default Value:

'false'

Possible Values:

'true' / 'false'

Description:

Returns 'true' if at least one condition of publish_pages_on matches the pipeline’s ref, otherwise returns 'false'.

Optimizations

This template offers no optimizations (reduced job runtime).