Documented TagReleaseCommit.

doc/JobTemplate/Package/InstallPackage.rst

@@ -20,7 +20,7 @@ the installation is verified. This aims for packaging and dependency mistakes in
 .. topic:: Job Execution
 
    .. image:: ../../_static/pyTooling-Actions-InstallPackage.png
-      :width: 600px
+      :width: 500px
 
 .. topic:: Dependencies
 

doc/JobTemplate/Release/TagReleaseCommit.rst

@@ -3,20 +3,204 @@
 TagReleaseCommit
 ################
 
-.. todo:: TagReleaseCommit:Needs documentation.
+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*.
 
-**Behavior:**
+.. note::
 
-.. todo:: TagReleaseCommit:Behavior needs documentation.
+   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.
 
-**Dependencies:**
+   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.
 
-.. todo:: TagReleaseCommit:Dependencies needs documentation.
+   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.
+
+.. topic:: Features
+
+   * Tag the current pipeline's commit.
+   * Trigger a new pipeline run for this new tag.
+
+.. topic:: Behavior
+
+   1. Tag the current commit with a tag named like :ref:`JOBTMPL/TagReleaseCommit/Input/version`.
+   2. Trigger a pipeline run for the new tag.
+
+.. topic:: Job Execution
+
+   .. image:: ../../_static/pyTooling-Actions-TagReleaseCommit.png
+      :width: 350px
+
+.. topic:: Dependencies
+
+   * :gh:`actions/github-script`
+
+
+.. _JOBTMPL/PrepareJob/Instantiation:
 
 Instantiation
 *************
 
-Simple Example
-==============
+The following instantiation example depicts three jobs within a bigger pipeline. The ``prepare`` job derived from job
+template ``PrepareJob`` version ``@r5`` 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 ``@r5``, or alternatively run the ``ReleasePage`` job derived from job template
+``PublishReleaseNotes`` version ``@r5``.
 
-.. todo:: TagReleaseCommit:Simple example needs documentation.
+.. code-block:: yaml
+
+   name: Pipeline
+
+   on:
+     push:
+     workflow_dispatch:
+
+   jobs:
+     Prepare:
+       uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r5
+
+     # Other pipeline jobs
+
+     TriggerTaggedRelease:
+       uses: pyTooling/Actions/.github/workflows/TagReleaseCommit.yml@r5
+       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@r5
+       needs:
+         - Prepare
+       if: needs.Prepare.outputs.is_release_tag == 'true'
+       permissions:
+         contents: write
+         actions:  write
+       with:
+         tag: ${{ needs.Prepare.outputs.version }}
+       secrets: inherit
+
+.. seealso::
+
+   :ref:`JOBTMPL/PrepareJob`
+     ``PrepareJob`` ...
+   :ref:`JOBTMPL/PublishReleaseNotes`
+     ``PublishReleaseNotes`` ...
+
+
+.. _JOBTMPL/TagReleaseCommit/Parameters:
+
+Parameter Summary
+*****************
+
+.. rubric:: Goto :ref:`input parameters <JOBTMPL/TagReleaseCommit/Inputs>`
+
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| Parameter Name                                                      | Required | Type     | Default                                                           |
++=====================================================================+==========+==========+===================================================================+
+| :ref:`JOBTMPL/TagReleaseCommit/Input/ubuntu_image`                  | no       | string   | ``'ubuntu-24.04'``                                                |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/TagReleaseCommit/Input/version`                       | yes      | string   | — — — —                                                           |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/TagReleaseCommit/Input/auto_tag`                      | yes      | string   | — — — —                                                           |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+| :ref:`JOBTMPL/TagReleaseCommit/Input/workflow`                      | no       | string   | ``'Pipeline.yml'``                                                |
++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+
+.. rubric:: Goto :ref:`secrets <JOBTMPL/TagReleaseCommit/Secrets>`
+
+This job template needs no secrets.
+
+.. rubric:: Goto :ref:`output parameters <JOBTMPL/TagReleaseCommit/Outputs>`
+
+This job template has no output parameters.
+
+
+.. _JOBTMPL/TagReleaseCommit/Inputs:
+
+Input Parameters
+****************
+
+.. _JOBTMPL/TagReleaseCommit/Input/ubuntu_image:
+
+ubuntu_image
+============
+
+:Type:            string
+:Required:        no
+:Default Value:   ``'ubuntu-24.04'``
+:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
+                  for available Ubuntu image versions.
+:Description:     Name of the Ubuntu image used to run this job.
+
+
+.. _JOBTMPL/TagReleaseCommit/Input/version:
+
+version
+=======
+
+:Type:            string
+:Required:        yes
+:Possible Values: Any valid Git tag name.
+:Description:     The version string to be used for tagging.
+
+
+.. _JOBTMPL/TagReleaseCommit/Input/auto_tag:
+
+auto_tag
+========
+
+:Type:            string
+:Required:        yes
+:Possible Values: ``'false'``, ``'true'```
+:Description:     If *true*, tag the current commit.
+
+
+.. _JOBTMPL/TagReleaseCommit/Input/workflow:
+
+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.
+
+
+.. _JOBTMPL/TagReleaseCommit/Secrets:
+
+Secrets
+*******
+
+This job template needs no secrets.
+
+
+.. _JOBTMPL/TagReleaseCommit/Outputs:
+
+Outputs
+*******
+
+This job template has no output parameters.
+
+
+.. _JOBTMPL/TagReleaseCommit/Optimizations:
+
+Optimizations
+*************
+
+This template offers no optimizations (reduced job runtime).

doc/JobTemplate/Setup/Parameters.rst

@@ -468,6 +468,7 @@ ubuntu_image
 :Required:        no
 :Default Value:   ``'ubuntu-24.04'``
 :Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
+                  for available Ubuntu image versions.
 :Description:     Name of the Ubuntu x86-64 image and version used to run a Ubuntu jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`.
 
 
@@ -480,6 +481,7 @@ ubuntu_arm_image
 :Required:        no
 :Default Value:   ``'ubuntu-24.04-arm'``
 :Possible Values: See `actions/partner-runner-images - Available Images <https://github.com/actions/partner-runner-images?tab=readme-ov-file#available-images>`__
+                  for available Ubuntu ARM image versions.
 :Description:     Name of the Ubuntu aarch64 image and version used to run a Ubuntu ARM jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`.
 
 

doc/JobTemplate/Setup/PrepareJob.rst

@@ -166,6 +166,7 @@ ubuntu_image
 :Required:        no
 :Default Value:   ``'ubuntu-24.04'``
 :Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
+                  for available Ubuntu image versions.
 :Description:     Name of the Ubuntu image used to run this job.
 
 

doc/JobTemplate/index.rst

@@ -76,6 +76,7 @@ ubuntu_image
 :Required:        usually no
 :Default Value:   ``'ubuntu-24.04'``
 :Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
+                  for available Ubuntu image versions.
 :Description:     Name of the Ubuntu image used to run a job.