TagReleaseCommit

The TagReleaseCommit job template creates a tag at the commit currently used by the pipeline run and then it triggers a new pipeline run for that tag, a.k.a tag pipeline or release pipeline.

Note

When the tag pipeline is launched, the pipeline is displayed in GitHub Actions with the name in the YAML file. In contrast, when a tag is manually added and pushed via Git on command line, the tag name is displayed.

Currently, no command, API or similar is known to add a tag and trigger a matching pipeline run, where the pipeline is named like the used tag. Thus, currently this job template has a slightly different behavior compared to manual tagging and pushing a tag to GitHub.

In addition, GitHub doesn’t support project access token, thus there is no solution to create a user independent token to emulate a manual push operation.

Hint

The run’s title can be corrected in the calling workflow, without changing how the run is triggered. A top-level run-name key overrides the title GitHub derives from the event, and github.ref_name holds the tag name for a run dispatched onto a tag:

name: Pipeline
run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }}

An empty run-name falls back to the title GitHub derives from the event, so only tag runs are renamed and a push keeps its commit message as the title.

This changes the displayed title only. It does not turn the workflow_dispatch event into a push event, so anything keying off github.event_name is unaffected. run-name is evaluated when the run is queued, so only the github, inputs and vars contexts are available - a value computed inside the pipeline, such as the version extracted by PrepareJob, cannot appear in the title.

Features

• Refuse to tag, if the tag or a release page for the version already exists.

• Tag the current pipeline’s commit.

• Trigger a new pipeline run for this new tag.

Behavior

1. Check that neither a tag nor a release page named like version exists.
   Otherwise the job fails before anything is tagged.

2. Tag the current commit with a tag named like version.

3. Trigger a pipeline run for the new tag (workflow).

The job is skipped unless auto_tag is 'true'. Tagging from a workflow does not trigger a tag pipeline by itself, which is why the third step dispatches the run explicitly.

See also

CheckReleaseVersion

Check early in a pipeline that a package registry has no release of the version yet.

Note

Because the run is started as a workflow_dispatch event and not by a tag push, GitHub titles it with the workflow’s name instead of the tag name. See the note at the top of this page for the reason and for a way to correct the displayed title.

Job Execution

Dependencies

• GitHub: actions/github-script

Instantiation

The following instantiation example depicts three jobs within a bigger pipeline. The prepare job derived from job template PrepareJob version @r8 figures out if a pipeline runs for a release merge-commit, for a tag or any other reason. Its outputs are used to either run a TriggerTaggedRelease job derived from job template TagReleaseCommit version @r8, or alternatively run the ReleasePage job derived from job template PublishReleaseNotes version @r8.

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

  # Other pipeline jobs

  TriggerTaggedRelease:
    uses: pyTooling/Actions/.github/workflows/TagReleaseCommit.yml@r8
    needs:
      - Prepare
    if: needs.Prepare.outputs.is_release_commit == 'true' && github.event_name != 'schedule'
    permissions:
      contents: write  # required for create tag
      actions:  write  # required for trigger workflow
    with:
      version:  ${{ needs.Prepare.outputs.version }}
      auto_tag: ${{ needs.Prepare.outputs.is_release_commit }}
    secrets: inherit

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

Parameter Summary

Goto input parameters

Parameter Name	Required	Type	Default
ubuntu_image	no	string	'ubuntu-26.04'
version	yes	string	— — — —
auto_tag	yes	string	— — — —
workflow	no	string	'Pipeline.yml'

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:

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.

version

Type:

string

Required:

yes

Default Value:

— — — —

Possible Values:

Any valid Git tag name.

Description:

The version string to be used for tagging.

auto_tag

Type:

string

Required:

yes

Default Value:

— — — —

Possible Values:

'true' / 'false'

Description:

Tag the current commit and dispatch the tag pipeline.
'true' - create the tag and trigger the run.
'false' - do nothing; the job’s steps are skipped.

workflow

Type:

string

Required:

no

Default Value:

'Pipeline.yml'

Possible Values:

Any valid GitHub Action pipeline filename.

Description:

Github Action pipeline (workflow) to trigger after tag creation.

Note

Compared to manual tagging and pushing a tag, where a pipeline is triggered automatically, here a pipeline must be trigger separately by API. Therefore the pipeline doesn’t run with the name of the tag, but with the name specified within the workflow YAML file.

Secrets

This job template needs no secrets.

Outputs

This job template has no output parameters.

Optimizations

This template offers no optimizations (reduced job runtime).