Skip to content

Commit 60db137

Browse files
PaebbelsPaebbels
committed
Documented TagReleaseCommit.
1 parent d62ba6c commit 60db137

File tree

8 files changed

+199
-11
lines changed

8 files changed

+199
-11
lines changed

‎.github/workflows/CompletePipeline.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -350,7 +350,7 @@ jobs:
350350
# - StaticTypeCheck
351351
- Package
352352
- PublishToGitHubPages
353-
if: needs.Prepare.outputs.is_release_commit && github.event_name != 'schedule'
353+
if: needs.Prepare.outputs.is_release_commit == 'true' && github.event_name != 'schedule'
354354
permissions:
355355
contents: write # required for create tag
356356
actions: write # required for trigger workflow

‎.github/workflows/TagReleaseCommit.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ jobs:
5454

5555
permissions:
5656
contents: write # required for tag creation
57-
actions: write # required to start a new pipeline
57+
actions: write # required to start a new pipeline
5858

5959
steps:
6060
- name: 🏷 Create release tag '${{ steps.FindPullRequest.outputs.version }}'

‎doc/JobTemplate/Package/InstallPackage.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ the installation is verified. This aims for packaging and dependency mistakes in
2020
.. topic:: Job Execution
2121

2222
.. image:: ../../_static/pyTooling-Actions-InstallPackage.png
23-
:width: 600px
23+
:width: 500px
2424

2525
.. topic:: Dependencies
2626

‎doc/JobTemplate/Release/TagReleaseCommit.rst‎

Lines changed: 192 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,204 @@
33
TagReleaseCommit
44
################
55

6-
.. todo:: TagReleaseCommit:Needs documentation.
6+
The ``TagReleaseCommit`` job template creates a tag at the commit currently used by the pipeline run and then it
7+
triggers a new pipeline run for that tag, a.k.a *tag pipeline* or *release pipeline*.
78

8-
**Behavior:**
9+
.. note::
910

10-
.. todo:: TagReleaseCommit:Behavior needs documentation.
11+
When the *tag pipeline* is launched, the pipeline is displayed in GitHub Actions with the name in the YAML file. In
12+
contrast, when a tag is manually added and pushed via Git on command line, the tag name is displayed.
1113

12-
**Dependencies:**
14+
Currently, no command, API or similar is known to add a tag and trigger a matching pipeline run, where the pipeline
15+
is named like the used tag. Thus, currently this job template has a slightly different behavior compared to manual
16+
tagging and pushing a tag to GitHub.
1317

14-
.. todo:: TagReleaseCommit:Dependencies needs documentation.
18+
In addition, GitHub doesn't support *project access token*, thus there is no solution to create a user independent
19+
token to emulate a manual push operation.
20+
21+
.. topic:: Features
22+
23+
* Tag the current pipeline's commit.
24+
* Trigger a new pipeline run for this new tag.
25+
26+
.. topic:: Behavior
27+
28+
1. Tag the current commit with a tag named like :ref:`JOBTMPL/TagReleaseCommit/Input/version`.
29+
2. Trigger a pipeline run for the new tag.
30+
31+
.. topic:: Job Execution
32+
33+
.. image:: ../../_static/pyTooling-Actions-TagReleaseCommit.png
34+
:width: 350px
35+
36+
.. topic:: Dependencies
37+
38+
* :gh:`actions/github-script`
39+
40+
41+
.. _JOBTMPL/PrepareJob/Instantiation:
1542

1643
Instantiation
1744
*************
1845

19-
Simple Example
20-
==============
46+
The following instantiation example depicts three jobs within a bigger pipeline. The ``prepare`` job derived from job
47+
template ``PrepareJob`` version ``@r5`` figures out if a pipeline runs for a release merge-commit, for a tag or any
48+
other reason. Its outputs are used to either run a ``TriggerTaggedRelease`` job derived from job template
49+
``TagReleaseCommit`` version ``@r5``, or alternatively run the ``ReleasePage`` job derived from job template
50+
``PublishReleaseNotes`` version ``@r5``.
51+
52+
.. code-block:: yaml
53+
54+
name: Pipeline
55+
56+
on:
57+
push:
58+
workflow_dispatch:
59+
60+
jobs:
61+
Prepare:
62+
uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r5
63+
64+
# Other pipeline jobs
65+
66+
TriggerTaggedRelease:
67+
uses: pyTooling/Actions/.github/workflows/TagReleaseCommit.yml@r5
68+
needs:
69+
- Prepare
70+
if: needs.Prepare.outputs.is_release_commit == 'true' && github.event_name != 'schedule'
71+
permissions:
72+
contents: write # required for create tag
73+
actions: write # required for trigger workflow
74+
with:
75+
version: ${{ needs.Prepare.outputs.version }}
76+
auto_tag: ${{ needs.Prepare.outputs.is_release_commit }}
77+
secrets: inherit
78+
79+
ReleasePage:
80+
uses: pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml@r5
81+
needs:
82+
- Prepare
83+
if: needs.Prepare.outputs.is_release_tag == 'true'
84+
permissions:
85+
contents: write
86+
actions: write
87+
with:
88+
tag: ${{ needs.Prepare.outputs.version }}
89+
secrets: inherit
90+
91+
.. seealso::
92+
93+
:ref:`JOBTMPL/PrepareJob`
94+
``PrepareJob`` ...
95+
:ref:`JOBTMPL/PublishReleaseNotes`
96+
``PublishReleaseNotes`` ...
97+
98+
99+
.. _JOBTMPL/TagReleaseCommit/Parameters:
100+
101+
Parameter Summary
102+
*****************
103+
104+
.. rubric:: Goto :ref:`input parameters <JOBTMPL/TagReleaseCommit/Inputs>`
105+
106+
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
107+
| Parameter Name | Required | Type | Default |
108+
+=====================================================================+==========+==========+===================================================================+
109+
| :ref:`JOBTMPL/TagReleaseCommit/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` |
110+
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
111+
| :ref:`JOBTMPL/TagReleaseCommit/Input/version` | yes | string | — — — — |
112+
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
113+
| :ref:`JOBTMPL/TagReleaseCommit/Input/auto_tag` | yes | string | — — — — |
114+
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
115+
| :ref:`JOBTMPL/TagReleaseCommit/Input/workflow` | no | string | ``'Pipeline.yml'`` |
116+
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
117+
118+
.. rubric:: Goto :ref:`secrets <JOBTMPL/TagReleaseCommit/Secrets>`
119+
120+
This job template needs no secrets.
121+
122+
.. rubric:: Goto :ref:`output parameters <JOBTMPL/TagReleaseCommit/Outputs>`
123+
124+
This job template has no output parameters.
125+
126+
127+
.. _JOBTMPL/TagReleaseCommit/Inputs:
128+
129+
Input Parameters
130+
****************
131+
132+
.. _JOBTMPL/TagReleaseCommit/Input/ubuntu_image:
133+
134+
ubuntu_image
135+
============
136+
137+
:Type: string
138+
:Required: no
139+
:Default Value: ``'ubuntu-24.04'``
140+
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
141+
for available Ubuntu image versions.
142+
:Description: Name of the Ubuntu image used to run this job.
143+
144+
145+
.. _JOBTMPL/TagReleaseCommit/Input/version:
146+
147+
version
148+
=======
149+
150+
:Type: string
151+
:Required: yes
152+
:Possible Values: Any valid Git tag name.
153+
:Description: The version string to be used for tagging.
154+
155+
156+
.. _JOBTMPL/TagReleaseCommit/Input/auto_tag:
157+
158+
auto_tag
159+
========
160+
161+
:Type: string
162+
:Required: yes
163+
:Possible Values: ``'false'``, ``'true'```
164+
:Description: If *true*, tag the current commit.
165+
166+
167+
.. _JOBTMPL/TagReleaseCommit/Input/workflow:
168+
169+
workflow
170+
========
171+
172+
:Type: string
173+
:Required: no
174+
:Default Value: ``'Pipeline.yml'``
175+
:Possible Values: Any valid GitHub Action pipeline filename.
176+
:Description: Github Action pipeline (workflow) to trigger after tag creation.
177+
178+
.. note::
179+
180+
Compared to manual tagging and pushing a tag, where a pipeline is triggered automatically, here a
181+
pipeline must be trigger separately by API. Therefore the pipeline doesn't run with the name of the
182+
tag, but with the name specified within the workflow YAML file.
183+
184+
185+
.. _JOBTMPL/TagReleaseCommit/Secrets:
186+
187+
Secrets
188+
*******
189+
190+
This job template needs no secrets.
191+
192+
193+
.. _JOBTMPL/TagReleaseCommit/Outputs:
194+
195+
Outputs
196+
*******
197+
198+
This job template has no output parameters.
199+
200+
201+
.. _JOBTMPL/TagReleaseCommit/Optimizations:
202+
203+
Optimizations
204+
*************
21205

22-
.. todo:: TagReleaseCommit:Simple example needs documentation.
206+
This template offers no optimizations (reduced job runtime).

‎doc/JobTemplate/Setup/Parameters.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -468,6 +468,7 @@ ubuntu_image
468468
:Required: no
469469
:Default Value: ``'ubuntu-24.04'``
470470
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
471+
for available Ubuntu image versions.
471472
: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`.
472473

473474

@@ -480,6 +481,7 @@ ubuntu_arm_image
480481
:Required: no
481482
:Default Value: ``'ubuntu-24.04-arm'``
482483
:Possible Values: See `actions/partner-runner-images - Available Images <https://github.com/actions/partner-runner-images?tab=readme-ov-file#available-images>`__
484+
for available Ubuntu ARM image versions.
483485
: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`.
484486

485487

‎doc/JobTemplate/Setup/PrepareJob.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,7 @@ ubuntu_image
166166
:Required: no
167167
:Default Value: ``'ubuntu-24.04'``
168168
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
169+
for available Ubuntu image versions.
169170
:Description: Name of the Ubuntu image used to run this job.
170171

171172

‎doc/JobTemplate/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ ubuntu_image
7676
:Required: usually no
7777
:Default Value: ``'ubuntu-24.04'``
7878
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
79+
for available Ubuntu image versions.
7980
:Description: Name of the Ubuntu image used to run a job.
8081

8182

‎doc/_static/pyTooling-Actions-TagReleaseCommit.png‎

19.5 KB
Loading

0 commit comments

Comments
 (0)