PublishReleaseNotes

This template creates a GitHub Release Page and uploads assets to that page.

Features

• Assembly a release description from various sources:

  • Description file in the repository.

  • Description via job template parameter.

  • Description from associated pull-request.

• Download artifact and upload selected files as assets to the release page.

• Add an inventory file in JSON format as asset to each release.

• Replace placeholders with variable contents.

• Override the release’s title.

• Create draft releases.

• Create pre-release release.

• Create nightly/rolling releases.

Behavior

1. Checkout repository.

2. Install dependencies.

3. Check if it’s a full release or nightly release (rolling release).

4. Delete old release.

5. Assemble release notes.

6. Create a new or recreate the release page as draft.

7. Attach files from artifacts as assets:

   1. Download artifact

   2. Optionally, create compressed archives of that content.

   3. Upload assets to release page.

8. Remove draft state from new release page.

Job Execution

Dependencies

• GitHub: actions/checkout

• gh (GitHub command line interface)

• jq (JSON processing)

• apt

  • zstd

Instantiation

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

  Release:
    uses: pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml@r5
    needs:
      - Prepare
    if: needs.Prepare.outputs.is_release_tag == 'true'
    permissions:
      contents: write
      actions:  write
    with:
      tag: ${{ needs.Prepare.outputs.version }}
    secrets: inherit

Release Notes

Providing a release description (a.k.a release page content) can be achieved from various sources. These sources can also be combined to a single description. Moreover, the resulting description can contain placeholders which can be replaced by values provided via parameter replacements.

Description text from file in the repository

The job template’s parameter description_file provides a way to read a predefined content from a file within the repository. This allows sharing the same text between nightly releases and full releases.

Note

This file can’t be computed/modified at pipeline runtime, because a fixed Git commit is checked out for this job template run.

Descriptions text from pipeline parameter

The job template’s parameter description provides a way to either hard code a release description in YAML code, or connect a GitHub Action variable ${{ ... }} to that parameter.

The content is available in replacement variable %%DESCRIPTION%%.

Description text from associated PullRequest

If an associated pull-request can be identified for a merge-commit, the pull-requests description can be used as a release description.

The content is available in replacement variable %%PULLREQUEST%%.

Additional text from description_footer

Additionally, a footer text is provided.

The content is available in replacement variable %%FOOTER%%.

Order of Processing

1. If description_file exists and is not empty, it will serve as the main description. If the description contains %%...%% placeholders, these placeholders will be replaced accordingly. If description contains %...% placeholders, replacement rules provided by replacements will be applied.

2. If description is not empty, it will serve as the main description. If the description contains %%...%% placeholders, these placeholders will be replaced accordingly. If description contains %...% placeholders, replacement rules provided by replacements will be applied.

3. If the associated pull-request exists and is not empty, it’s description will serve as the main description. If the description contains %%...%% placeholders, these placeholders will be replaced accordingly. If description contains %...% placeholders, replacement rules provided by replacements will be applied.

4. Otherwise, an error is raised.

Replacements

%%DESCRIPTION%%

Replaces the placeholder with the content from description.

%%PULLREQUEST%%, %%PULLREQUEST+0%%, %%PULLREQUEST+1%%, %%PULLREQUEST+2%%, %%PULLREQUEST+3%%

Replaces the content by the associated pull-requests description text.

If an indentation level +N (+1, +2, +3) is specified, headlines in the pull-request description will be moved by N levels down.

%%FOOTER%%

Replaces the placeholder with the content from description_footer.

%%gh_server%%

Replaced by the GitHub server URL.
The value is derived from ${{ github.server_url }}.

%%gh_workflow_name%%

Replaced by the workflow name.
The value is derived from ${{ github.workflow }}.

%%gh_owner%%

Replaced by the repository owner, which is either the name of a GitHub organisation or a GitHub user account.
The value is derived from ${{ github.repository_owner }}.

%%gh_repo%%

Replaced by the repository name.
The value is derived from ${{ github.repository }} by splitting namespace and repository name into the ${repo} variable.

%%gh_owner_repo%%

Replaced by the repository slug, which is either the name of a GitHub organisation or a GitHub user account followed by the repository name concatenated by the slash character.
The value is derived from ${{ github.repository }}.

%%gh_pages%%

Replaced by the URL to the associated GitHub Pages webspace.
The value is formatted as https://${{ github.repository_owner }}.github.io/${repo}.

%%gh_runid%%

Replaced by the pipelines ID.
The value is derived from ${{ github.run_id }}

%%gh_actor%%

Replaced by the actor (user or bot), who launched the pipeline.
The value is derived from ${{ github.actor }}.

%%gh_sha%%

Replaced by the associated commit’s SHA.
The value is derived from ${{ github.sha }}

%%date%%

Replaced by the current date.
The value is formatted as $(date '+%Y-%m-%d').

%%time%%

Replaced by the current date.
The value is formatted as $(date '+%H:%M:%S %Z').

%%datetime%%

Replaced by the current date.
The value is formatted as $(date '+%Y-%m-%d %H:%M:%S %Z').

Examples

Todo

• GHDL - uses description_file and description

• pyTooling - uses pullrequest

Assets

Todo

PublishReleaseNotes::Assets Describe artifact to asset transformation

Format: artifact:file:title

See also: replacements

Inventory

Todo

PublishReleaseNotes::Inventory Describe how inventory files are created.

Parameter Summary

Goto input parameters

Parameter Name	Required	Type	Default
ubuntu_image	no	string	'ubuntu-24.04'
release_branch	no	string	'main'
mode	no	string	'release'
tag	yes	string	— — — —
title	no	string	''
description	no	string	''
description_file	no	string	''
description_footer	no	string	see parameter details
draft	no	boolean	false
prerelease	no	boolean	false
latest	no	boolean	false
replacements	no	string	''
assets	no	string	''
inventory-json	no	string	''
inventory-version	no	string	''
inventory-categories	no	string	''
tarball-name	no	string	'__pyTooling_upload_artifact__.tar'
can-fail	no	boolean	false

Goto secrets

This job template needs no secrets.

Goto output parameters

This job template has no output parameters.

Input Parameters

ubuntu_image

Type:

string

Required:

usually 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 a job.

release_branch

Type:

string

Required:

no

Default Value:

'main'

Possible Values:

Any valid Git branch name.

Description:

Name of the branch containing releases.

mode

Type:

string

Required:

no

Default Value:

'release'

Possible Values:

'release', 'nightly'

Description:

The release mode, which is either nightly (a.k.a rolling release) or release.

tag

Type:

string

Required:

yes

Default Value:

— — — —

Possible Values:

Any valid Git tag name.

Description:

Name of the release (tag).

Condition:

It must match an existing tag name in the repository.

title

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid string suitable for a release title (headline).

Description:

If this parameter is not empty, the releases title is set, which overrides the default title inferred from the associated tag name.

description

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid (multi-line) Markdown string.

Description:

The description of the release usually used to render the release notes.
See Release Notes for more details.

description_file

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid Markdown file.
Suggested value: .github/ReleaseDescription.md.

Description:

Path to a Markdown file used for the release description.
See Release Notes for more details.

description_footer

Type:

string

Required:

no

Default Value:

--------
Published from [%%gh_workflow_name%%](%%gh_server%%/%%gh_owner_repo%%/actions/runs/%%gh_runid%%) workflow triggered by %%gh_actor%% on %%datetime%%.

This automatic release was created by [pyTooling/Actions](http://github.com/pyTooling/Actions)::Release.yml

Possible Values:

Any valid (multi-line) Markdown text.

Description:

A footer added to the description.
See Release Notes for more details.

draft

Type:

boolean

Required:

no

Default Value:

false

Possible Values:

false, true

Description:

If true, the release is kept in draft state.

Note

GitHub doesn’t send e-mail notifications to subscribed users for draft releases.

prerelease

Type:

boolean

Required:

no

Default Value:

false

Possible Values:

false, true

Description:

If true, the release is marked as a pre-release.

latest

Type:

boolean

Required:

no

Default Value:

false

Possible Values:

false, true

Description:

If true, the release is marked as latest release.

replacements

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid multi-line string of format search=replace patterns.

Description:

The given replacements are used to replace placeholders in description, description_file, description_footer.
See Release Notes for more details.

Example:

The following example replaces the placeholder %version% with the actual version number (inferred from tag name by PrepareJob.

ReleasePage:
  uses: pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml@r5
  needs:
    - Prepare
  if: needs.Prepare.outputs.is_release_tag == 'true'
  permissions:
    contents: write
    actions:  write
  with:
    tag: ${{ needs.Prepare.outputs.version }}
    description: |
      # myPackage %version%

      This is the latest release of myPackage.
    replacements: |
      version=${{ needs.Prepare.outputs.version }}

assets

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid multi-line string containing artifact to asset transformations.
The artifact:file:title format is explained at Assets

Description:

Each line describes which artifacts to download and extract as well as which extracted file to upload as a release asset. The files title can be changed.
Replacement rules from parameter replacements can be used, too.
See Assets for more details.

inventory-json

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid JSON filename.
Suggested value: inventory.json.

Description:

If this parameter is not empty, an inventory of all assets will be created and attached as a JSON file to the release.
See Inventory for more details.

inventory-version

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid version string.

Description:

If this parameter is not empty, the version field in the inventory JSON is set to this value.
See Inventory for more details.

Hint

Especially for nightly/rolling releases, the used Git tag is a name rather then a version number. Therefore, a version number must be provided thus a nightly release can be identified as vX.Y.Z.

inventory-categories

Type:

string

Required:

no

Default Value:

''

Possible Values:

A colon separated list of identifiers used as category names in an inventory JSON.

Description:

For decoding hierarchy levels (categories) in an inventory JSON, the hierarchy of categories can be added to the inventoy JSON.
See Inventory for more details.

tarball-name

Type:

string

Required:

no

Default Value:

'__pyTooling_upload_artifact__.tar'

Possible Values:

Any valid name for a tarball file.

Description:

Todo

PublishReleaseNotes::tarball-name Needs documentation.

can-fail

Type:

boolean

Required:

no

Default Value:

false

Possible Values:

false, true

Description:

Todo

PublishReleaseNotes::can-fail Needs documentation.

Secrets

This job template needs no secrets.

Outputs

release-page

Type:

string

Description:

Returns the URL to the release page.

Example:

tbd

Optimizations

This template offers no optimizations (reduced job runtime).