diff --git a/.github/workflows/CompletePipeline.yml b/.github/workflows/CompletePipeline.yml index b50d518..cf9ae86 100644 --- a/.github/workflows/CompletePipeline.yml +++ b/.github/workflows/CompletePipeline.yml @@ -350,7 +350,7 @@ jobs: # - StaticTypeCheck - Package - PublishToGitHubPages - if: needs.Prepare.outputs.is_release_commit && github.event_name != 'schedule' + 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 diff --git a/.github/workflows/TagReleaseCommit.yml b/.github/workflows/TagReleaseCommit.yml index d110164..8ccad9d 100644 --- a/.github/workflows/TagReleaseCommit.yml +++ b/.github/workflows/TagReleaseCommit.yml @@ -54,7 +54,7 @@ jobs: permissions: contents: write # required for tag creation - actions: write # required to start a new pipeline + actions: write # required to start a new pipeline steps: - name: 🏷 Create release tag '${{ steps.FindPullRequest.outputs.version }}' diff --git a/.github/workflows/_Checking_AvailableRunners.yml b/.github/workflows/_Checking_AvailableRunners.yml index cd838b0..e651027 100644 --- a/.github/workflows/_Checking_AvailableRunners.yml +++ b/.github/workflows/_Checking_AvailableRunners.yml @@ -22,7 +22,7 @@ jobs: - {icon: '🍏', name: 'macOS-14 (aarch64)', image: 'macos-14', shell: 'bash'} # latest - {icon: '🍏', name: 'macOS-15 (aarch64)', image: 'macos-15', shell: 'bash'} - {icon: '🪟', name: 'Windows Server 2022', image: 'windows-2022', shell: 'bash'} - - {icon: '🪟', name: 'Windows Server 2025', image: 'windows-2022', shell: 'bash'} # latest + - {icon: '🪟', name: 'Windows Server 2025', image: 'windows-2025', shell: 'bash'} # latest # Third party images by ARM for aarch64 - {icon: '🐧', name: 'Ubuntu 22.04 (aarch64)', image: 'ubuntu-22.04-arm', shell: 'bash'} - {icon: '🐧', name: 'Ubuntu 24.04 (aarch64)', image: 'ubuntu-24.04-arm', shell: 'bash'} diff --git a/doc/JobTemplate/Package/InstallPackage.rst b/doc/JobTemplate/Package/InstallPackage.rst index 96887d9..bd8af99 100644 --- a/doc/JobTemplate/Package/InstallPackage.rst +++ b/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 diff --git a/doc/JobTemplate/Release/TagReleaseCommit.rst b/doc/JobTemplate/Release/TagReleaseCommit.rst index 5371dbe..468737c 100644 --- a/doc/JobTemplate/Release/TagReleaseCommit.rst +++ b/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 ` + ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| 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 ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +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 `__ + 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). diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index b3f9894..114c557 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/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 `__ + 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 `__ + 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`. diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index 828e3e9..b11cff4 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/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 `__ + for available Ubuntu image versions. :Description: Name of the Ubuntu image used to run this job. diff --git a/doc/JobTemplate/index.rst b/doc/JobTemplate/index.rst index 7c2dbbf..e53db4a 100644 --- a/doc/JobTemplate/index.rst +++ b/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 `__ + for available Ubuntu image versions. :Description: Name of the Ubuntu image used to run a job. diff --git a/doc/_static/pyTooling-Actions-TagReleaseCommit.png b/doc/_static/pyTooling-Actions-TagReleaseCommit.png new file mode 100644 index 0000000..d7a4636 Binary files /dev/null and b/doc/_static/pyTooling-Actions-TagReleaseCommit.png differ