pyTooling/Actions
1
0
Fork 0
mirror of https://github.com/pyTooling/Actions.git synced 2026-02-12 02:56:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updated CompletePipeline.

Browse Source
This commit is contained in:
Patrick Lehmann
2025-08-23 01:09:58 +02:00
parent 4f49964e57
commit 6d75b849f5
4 changed files with 415 additions and 381 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
doc/JobTemplate/Setup/PrepareJob.rst
View File

@@ -25,7 +25,7 @@ The job template generates various output parameters derived from
Due to GitHub Action's broken type system and missing implicit type conversions in YAML files, *boolean* values need
to be returned as *string* values otherwise type compatibility and comparison are broken. This also requires all
inputs to be *string* parameters, otherwise an step's, job's or template's output cannot be assigned to a template's
inputs to be *string* parameters, otherwise step's, job's or template's output cannot be assigned to a template's
input.
**Problems:**
@@ -39,6 +39,11 @@ The job template generates various output parameters derived from
comparison will not work as expected. Either the comparison works with ``inputs.param == false`` for the default
value, **or** it works with a value from ``${{ needs }}`` context, which is a string ``inputs.param == 'false'``.
.. topic:: Job Execution
.. image:: ../../_static/pyTooling-Actions-PrepareJob.png
:width: 600px
.. topic:: Dependencies
* :gh:`actions/checkout`
@@ -50,10 +55,10 @@ The job template generates various output parameters derived from
Instantiation
*************
Simple Example
==============
The following instantiation example creates a job `Params` derived from job template `PrepareJob` version `r5`.
The following instantiation example creates a job ``Prepare`` derived from job template ``PrepareJob`` version ``@r5``.
In a default usecase, no input parameters need to be specified for the job template assuming a main-branch and
release-branch called ``main``, a development-branch called ``dev``, as well as semantic versioning for tags and
pull-request titles.
.. code-block:: yaml
@@ -75,69 +80,84 @@ The following instantiation example creates a job `Params` derived from job temp
with:
version: ${{ needs.Prepare.outputs.version }}
.. seealso::
:ref:`JOBTMPL/TagReleaseCommit`
``PrepareJob`` is usualy used to identify if a pipeline's commit is a merge commit created by a pull-request. If
so, this commit can be tagged automatically to trigger a release pipeline (tag pipeline) for the same commit
resulting in a full release (PyPI, GitHub Pages, GitHub Release, ...).
:ref:`JOBTMPL/PublishReleaseNotes`
``PrepareJob`` is usually used to identify if a tag pipeline is a release pipeline.
.. _JOBTMPL/PrepareJob/Parameters:
Parameters
**********
Parameter Summary
*****************
.. topic:: Parameter Summary
.. rubric:: Goto :ref:`input parameters <JOBTMPL/PrepareJob/Inputs>`
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=====================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/PrepareJob/Param/ubuntu_image` | no | string | ``'ubuntu-24.04'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Param/main_branch` | no | string | ``'main'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Param/development_branch` | no | string | ``'dev'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Param/release_branch` | no | string | ``'main'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Param/nightly_tag_pattern` | no | string | ``'nightly'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern` | no | string | ``'(v|r)?[0-9]+(\.[0-9]+){0,2}(-(dev|alpha|beta|rc)([0-9]*))?'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=====================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/PrepareJob/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Input/main_branch` | no | string | ``'main'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Input/development_branch` | no | string | ``'dev'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Input/release_branch` | no | string | ``'main'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Input/nightly_tag_pattern` | no | string | ``'nightly'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern` | no | string | ``'(v|r)?[0-9]+(\.[0-9]+){0,2}(-(dev|alpha|beta|rc)([0-9]*))?'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
.. topic:: :ref:`Secret Summary <JOBTMPL/PrepareJob/Secrets>`
.. rubric:: Goto Goto :ref:`secrets <JOBTMPL/PrepareJob/Secrets>`
This job template needs no secrets.
This job template needs no secrets.
.. topic:: :ref:`Output Summary <JOBTMPL/PrepareJob/Results>`
.. rubric:: Goto Goto :ref:`output parameters <JOBTMPL/PrepareJob/Outputs>`
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| Result Name | Type | Description |
+=====================================================================+==========+===================================================================+
| :ref:`JOBTMPL/PrepareJob/Result/on_main_branch` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/on_dev_branch` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/on_release_branch` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/is_regular_commit` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/is_merge_commit` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/is_release_commit` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/is_nightly_tag` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/is_release_tag` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/ref_kind` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/branch` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/tag` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/version` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/pr_title` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Result/pr_number` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| Result Name | Type | Description |
+=====================================================================+==========+===================================================================+
| :ref:`JOBTMPL/PrepareJob/Output/on_main_branch` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/on_dev_branch` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/on_release_branch` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/is_regular_commit` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/is_merge_commit` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/is_release_commit` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/is_nightly_tag` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/is_release_tag` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/ref_kind` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/branch` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/tag` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/version` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/pr_title` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PrepareJob/Output/pr_number` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
.. _JOBTMPL/PrepareJob/Param/ubuntu_image:
.. _JOBTMPL/PrepareJob/Inputs:
Input Parameters
****************
.. _JOBTMPL/PrepareJob/Input/ubuntu_image:
ubuntu_image
============
@@ -149,7 +169,7 @@ ubuntu_image
:Description: Name of the Ubuntu image used to run this job.
.. _JOBTMPL/PrepareJob/Param/main_branch:
.. _JOBTMPL/PrepareJob/Input/main_branch:
main_branch
===========
@@ -161,7 +181,7 @@ main_branch
:Description: Name of the main branch.
.. _JOBTMPL/PrepareJob/Param/development_branch:
.. _JOBTMPL/PrepareJob/Input/development_branch:
development_branch
==================
@@ -173,7 +193,7 @@ development_branch
:Description: Name of the development branch.
.. _JOBTMPL/PrepareJob/Param/release_branch:
.. _JOBTMPL/PrepareJob/Input/release_branch:
release_branch
==============
@@ -185,7 +205,7 @@ release_branch
:Description: Name of the branch containing releases.
.. _JOBTMPL/PrepareJob/Param/nightly_tag_pattern:
.. _JOBTMPL/PrepareJob/Input/nightly_tag_pattern:
nightly_tag_pattern
===================
@@ -199,7 +219,7 @@ nightly_tag_pattern
.. _JOBTMPL/PrepareJob/Param/release_tag_pattern:
.. _JOBTMPL/PrepareJob/Input/release_tag_pattern:
release_tag_pattern
===================
@@ -232,12 +252,12 @@ Secrets
This job template needs no secrets.
.. _JOBTMPL/PrepareJob/Results:
.. _JOBTMPL/PrepareJob/Outputs:
Results
Outputs
*******
.. _JOBTMPL/PrepareJob/Result/on_main_branch:
.. _JOBTMPL/PrepareJob/Output/on_main_branch:
on_main_branch
==============
@@ -245,11 +265,11 @@ on_main_branch
:Type: string
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`main branch <JOBTMPL/PrepareJob/Param/main_branch>`,
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`main branch <JOBTMPL/PrepareJob/Input/main_branch>`,
otherwise return ``'false'``.
.. _JOBTMPL/PrepareJob/Result/on_dev_branch:
.. _JOBTMPL/PrepareJob/Output/on_dev_branch:
on_dev_branch
=============
@@ -257,11 +277,11 @@ on_dev_branch
:Type: string
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`development branch <JOBTMPL/PrepareJob/Param/development_branch>`,
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`development branch <JOBTMPL/PrepareJob/Input/development_branch>`,
otherwise return ``'false'``.
.. _JOBTMPL/PrepareJob/Result/on_release_branch:
.. _JOBTMPL/PrepareJob/Output/on_release_branch:
on_release_branch
=================
@@ -269,11 +289,11 @@ on_release_branch
:Type: string
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`release branch <JOBTMPL/PrepareJob/Param/release_branch>`,
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`release branch <JOBTMPL/PrepareJob/Input/release_branch>`,
otherwise return ``'false'``.
.. _JOBTMPL/PrepareJob/Result/is_regular_commit:
.. _JOBTMPL/PrepareJob/Output/is_regular_commit:
is_regular_commit
=================
@@ -281,11 +301,11 @@ is_regular_commit
:Type: string
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns ``'true'`` if the pipeline's commit is not a :ref:`merge commit <JOBTMPL/PrepareJob/Result/is_merge_commit>`
nor :ref:`release commit <JOBTMPL/PrepareJob/Result/is_release_commit>`, otherwise return ``'false'``.
:Description: Returns ``'true'`` if the pipeline's commit is not a :ref:`merge commit <JOBTMPL/PrepareJob/Output/is_merge_commit>`
nor :ref:`release commit <JOBTMPL/PrepareJob/Output/is_release_commit>`, otherwise return ``'false'``.
.. _JOBTMPL/PrepareJob/Result/is_merge_commit:
.. _JOBTMPL/PrepareJob/Output/is_merge_commit:
is_merge_commit
===============
@@ -293,12 +313,12 @@ is_merge_commit
:Type: string
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`main branch <JOBTMPL/PrepareJob/Param/main_branch>`
or :ref:`development branch <JOBTMPL/PrepareJob/Param/development_branch>` and has more than one
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`main branch <JOBTMPL/PrepareJob/Input/main_branch>`
or :ref:`development branch <JOBTMPL/PrepareJob/Input/development_branch>` and has more than one
parent (merge commit), otherwise return ``'false'``.
.. _JOBTMPL/PrepareJob/Result/is_release_commit:
.. _JOBTMPL/PrepareJob/Output/is_release_commit:
is_release_commit
=================
@@ -306,11 +326,11 @@ is_release_commit
:Type: string
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`release branch <JOBTMPL/PrepareJob/Param/release_branch>`
:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`release branch <JOBTMPL/PrepareJob/Input/release_branch>`
and has more than one parent (merge commit), otherwise return ``'false'``.
.. _JOBTMPL/PrepareJob/Result/is_nightly_tag:
.. _JOBTMPL/PrepareJob/Output/is_nightly_tag:
is_nightly_tag
==============
@@ -318,12 +338,12 @@ is_nightly_tag
:Type: string
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns ``'true'`` if the pipeline is a tag pipeline for a commit on :ref:`release branch <JOBTMPL/PrepareJob/Param/release_branch>`
and the tag's name matches the :ref:`nightly tag pattern <JOBTMPL/PrepareJob/Param/nightly_tag_pattern>`,
:Description: Returns ``'true'`` if the pipeline is a tag pipeline for a commit on :ref:`release branch <JOBTMPL/PrepareJob/Input/release_branch>`
and the tag's name matches the :ref:`nightly tag pattern <JOBTMPL/PrepareJob/Input/nightly_tag_pattern>`,
otherwise return ``'false'``.
.. _JOBTMPL/PrepareJob/Result/is_release_tag:
.. _JOBTMPL/PrepareJob/Output/is_release_tag:
is_release_tag
==============
@@ -331,12 +351,12 @@ is_release_tag
:Type: string
:Default Value: ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns ``'true'`` if the pipeline is a tag pipeline for a commit on :ref:`release branch <JOBTMPL/PrepareJob/Param/release_branch>`
and the tag's name matches the :ref:`release tag pattern <JOBTMPL/PrepareJob/Param/release_tag_pattern>`,
:Description: Returns ``'true'`` if the pipeline is a tag pipeline for a commit on :ref:`release branch <JOBTMPL/PrepareJob/Input/release_branch>`
and the tag's name matches the :ref:`release tag pattern <JOBTMPL/PrepareJob/Input/release_tag_pattern>`,
otherwise return ``'false'``.
.. _JOBTMPL/PrepareJob/Result/ref_kind:
.. _JOBTMPL/PrepareJob/Output/ref_kind:
ref_kind
========
@@ -347,12 +367,12 @@ ref_kind
:Description: Returns ``'branch'`` if pipeline's commit is on a branch or returns ``'tag'`` if the pipeline runs for
a tagged commit, otherwise returns ``'unknown'`` in case of an internal error.
If the kind is a branch, the branch name is available in the job's :ref:`JOBTMPL/PrepareJob/Result/branch`
If the kind is a branch, the branch name is available in the job's :ref:`JOBTMPL/PrepareJob/Output/branch`
result. |br|
If the kind is a tag, the tags name is available in the job's :ref:`JOBTMPL/PrepareJob/Result/tag`
If the kind is a tag, the tags name is available in the job's :ref:`JOBTMPL/PrepareJob/Output/tag`
result. |br|
Moreover, if the tag matches the :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, the extracted
version is available in the job's :ref:`JOBTMPL/PrepareJob/Result/version` result.
Moreover, if the tag matches the :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, the extracted
version is available in the job's :ref:`JOBTMPL/PrepareJob/Output/version` result.
.. note::
@@ -361,7 +381,7 @@ ref_kind
and derives if a pipeline runs for a commit on a branch or a tagged commit.
.. _JOBTMPL/PrepareJob/Result/branch:
.. _JOBTMPL/PrepareJob/Output/branch:
branch
======
@@ -369,10 +389,10 @@ branch
:Type: string
:Default Value: ``''``
:Possible Values: Any valid branch name.
:Description: Returns the branch's name the pipeline's commit is associated to, if :ref:`JOBTMPL/PrepareJob/Result/ref_kind`
:Description: Returns the branch's name the pipeline's commit is associated to, if :ref:`JOBTMPL/PrepareJob/Output/ref_kind`
is ``'branch'``, otherwise returns an empty string ``''``.
.. _JOBTMPL/PrepareJob/Result/tag:
.. _JOBTMPL/PrepareJob/Output/tag:
tag
===
@@ -380,28 +400,28 @@ tag
:Type: string
:Default Value: ``''``
:Possible Values: Any valid tag name.
:Description: Returns the tag's name the pipeline's commit is associated to, if :ref:`JOBTMPL/PrepareJob/Result/ref_kind`
:Description: Returns the tag's name the pipeline's commit is associated to, if :ref:`JOBTMPL/PrepareJob/Output/ref_kind`
is ``'tag'``, otherwise returns an empty string ``''``.
.. _JOBTMPL/PrepareJob/Result/version:
.. _JOBTMPL/PrepareJob/Output/version:
version
=======
:Type: string
:Default Value: ``''``
:Possible Values: Any valid version matching :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`.
:Possible Values: Any valid version matching :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`.
:Description: In case the pipeline runs for a tag, it returns the tag's name, if the name matches
:ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, otherwise returns an empty string ``''``. |br|
:ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, otherwise returns an empty string ``''``. |br|
In case the pipeline runs for a branch, then the commit is checked if it's a
:ref:`merge commit <JOBTMPL/PrepareJob/Result/is_merge_commit>` and corresponding pull-request (PR) is
:ref:`merge commit <JOBTMPL/PrepareJob/Output/is_merge_commit>` and corresponding pull-request (PR) is
searched. When a matching PR can be located and it's title matches
:ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, then this title is returned as a version,
:ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, then this title is returned as a version,
otherwise it returns an empty string ``''``.
.. _JOBTMPL/PrepareJob/Result/pr_title:
.. _JOBTMPL/PrepareJob/Output/pr_title:
pr_title
========
@@ -410,12 +430,12 @@ pr_title
:Default Value: ``''``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns the associated pull-request's title, if the pipeline's commit is a
:ref:`merge commit <JOBTMPL/PrepareJob/Result/is_merge_commit>` and the located pull-request's title
for this commit matches :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, otherwise returns an
:ref:`merge commit <JOBTMPL/PrepareJob/Output/is_merge_commit>` and the located pull-request's title
for this commit matches :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, otherwise returns an
empty string ``''``.
.. _JOBTMPL/PrepareJob/Result/pr_number:
.. _JOBTMPL/PrepareJob/Output/pr_number:
pr_number
=========
@@ -424,6 +444,6 @@ pr_number
:Default Value: ``''``
:Possible Values: ``'true'``, ``'false'``
:Description: Returns the associated pull-request's number, if the pipeline's commit is a
:ref:`merge commit <JOBTMPL/PrepareJob/Result/is_merge_commit>` and the located pull-request's title
for this commit matches :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, otherwise returns an
:ref:`merge commit <JOBTMPL/PrepareJob/Output/is_merge_commit>` and the located pull-request's title
for this commit matches :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, otherwise returns an
empty string ``''``.