diff --git a/doc/Action/Releaser.rst b/doc/Action/Releaser.rst index d410da6..69b7328 100644 --- a/doc/Action/Releaser.rst +++ b/doc/Action/Releaser.rst @@ -1,3 +1,195 @@ +.. _ACTION/Releaser: + Releaser ######## +**Releaser** is a Docker GitHub Action written in Python. + +**Releaser** allows to keep a GitHub Release of type pre-release and its artifacts up to date with latest builds. +Combined with a workflow that is executed periodically, **Releaser** allows to provide a fixed release name for users +willing to use daily/nightly artifacts of a project. + +Furthermore, when any `semver `__ compliant tagged commit is pushed, **Releaser** can create a +release and upload assets. + +Context +******* + +GitHub provides official clients for the GitHub API through `github.com/octokit `__: + +- `octokit.js `__ (`octokit.github.io/rest.js `__) +- `octokit.rb `__ (`octokit.github.io/octokit.rb `__) +- `octokit.net `__ (`octokitnet.rtfd.io `__) + +When GitHub Actions was released in 2019, two Actions were made available through +`github.com/actions `__ for dealing with GitHub Releases: + +- `actions/create-release `__ +- `actions/upload-release-asset `__ + +However, those Actions were contributed by an employee in spare time, not officially supported by GitHub. +Therefore, they were unmaintained before GitHub Actions was out of the private beta +(see `actions/upload-release-asset#58 `__) +and, a year later, archived. +Those Actions are based on `actions/toolkit `__'s hydrated version of octokit.js. + +From a practical point of view, `actions/github-script `__ is the natural replacement to those Actions, since it allows to use a pre-authenticated *octokit.js* client along with the workflow run context. +Still, it requires writing plain JavaScript. + +Alternatively, there are non-official GitHub API libraries available in other languages (see `docs.github.com: rest/overview/libraries `__). +**Releaser** is based on `PyGithub/PyGithub `__, a Python client for the GitHub API. + +**Releaser** was originally created in `eine/tip `__, as an enhanced alternative to using +``actions/create-release`` and ``actions/upload-release-asset``, in order to cover certain use cases that were being +migrated from Travis CI to GitHub Actions. +The main limitation of GitHub's Actions was/is verbosity and not being possible to dynamically define the list of assets +to be uploaded. + +On the other hand, GitHub Actions artifacts do require login in order to download them. +Conversely, assets of GitHub Releases can be downloaded without login. +Therefore, in order to make CI results available to the widest audience, some projects prefer having tarballs available +as assets. +In this context, one of the main use cases of **Releaser** is pushing artifacts as release assets. +Thus, the name of the Action. + +GitHub provides an official CLI tool, written in golang: `cli/cli `__. +When the Python version of **Releaser** was written, ``cli`` was evaluated as an alternative to *PyGitHub*. +``gh release`` was (and still is) not flexible enough to update the reference of a release, without deleting and +recreating it (see `cli.github.com: manual/gh_release_create `__). +Deletion and recreation is unfortunate, because it notifies all the watchers of a repository +(see `eine/tip#111 `__). +However, `cli.github.com: manual/gh_release_upload `__ handles uploading +artifacts as assets faster and with better stability for larger files than *PyGitHub* +(see `msys2/msys2-installer#36 `__). +Furthermore, the GitHub CLI is installed on GitHub Actions' default virtual environments. +Although ``gh`` does not support login through SSH (see `cli/cli#3715 `__), on GitHub +Actions a token is available ``${{ github.token }}``. +Therefore, **Releaser** uses ``gh release upload`` internally. + +Usage +***** + +The following block shows a minimal YAML workflow file: + +.. code-block:: yaml + + name: 'workflow' + + on: + schedule: + - cron: '0 0 * * 5' + + jobs: + mwe: + runs-on: ubuntu-latest + steps: + + # Clone repository + - uses: actions/checkout@v2 + + # Build your application, tool, artifacts, etc. + - name: Build + run: | + echo "Build some tool and generate some artifacts" > artifact.txt + + # Update tag and pre-release + # - Update (force-push) tag to the commit that is used in the workflow. + # - Upload artifacts defined by the user. + - uses: pyTooling/Actions/releaser@r0 + with: + token: ${{ secrets.GITHUB_TOKEN }} + files: | + artifact.txt + README.md + + +Composite Action +================ + +The default implementation of **Releaser** is a Container Action. +Therefore, a pre-built container image is pulled before starting the job. +Alternatively, a Composite Action version is available: ``uses: pyTooling/Actions/releaser/composite@main``. +The Composite version installs the dependencies on the host (the runner environment), instead of using a container. +Both implementations are functionally equivalent from **Releaser**'s point of view; however, the Composite Action allows +users to tweak the version of Python by using `actions/setup-python `__ before. + +Options +******* + +All options can be optionally provided as environment variables: ``INPUT_TOKEN``, ``INPUT_FILES``, ``INPUT_TAG``, ``INPUT_RM`` +and/or ``INPUT_SNAPSHOTS``. + +token (required) +================ + +Token to make authenticated API calls; can be passed in using ``{{ secrets.GITHUB_TOKEN }}``. + +files (required) +================ + +Either a single filename/pattern or a multi-line list can be provided. All the artifacts are uploaded regardless of the +hierarchy. + +For creating/updating a release without uploading assets, set ``files: none``. + +tag +=== + +The default tag name for the tip/nightly pre-release is ``tip``, but it can be optionally overriden through option ``tag``. + +rm +== + +Set option ``rm`` to ``true`` for systematically removing previous artifacts (e.g. old versions). +Otherwise (by default), all previours artifacts are preserved or overwritten. + +Note: + If all the assets are removed, or if the release itself is removed, tip/nightly assets won't be available for + users until the workflow is successfully run. + For instance, Action `setup-ghdl-ci `__ uses assets from `ghdl/ghdl: releases/tag/nightly `__. + Hence, it is recommended to try removing the conflictive assets only, in order to maximise the availability. + +snapshots +========= + +Whether to create releases from any tag or to treat some as snapshots. +By default, all the tags with non-empty ``prerelease`` field (see `semver.org: Is there a suggested regular expression (RegEx) to check a SemVer string? `__) +are considered snapshots; neither a release is created nor assets are uploaded. + +Advanced/complex use cases +************************** + +**Releaser** is essentially a very thin wrapper to use the GitHub Actions context data along with the classes +and methods of PyGithub. + +Similarly to `actions/github-script `__, users with advanced/complex requirements +might find it desirable to write their own Python script, instead of using **Releaser**. +In fact, since ``shell: python`` is supported in GitHub Actions, using Python does *not* require any Action. +For prototyping purposes, the following job might be useful: + +.. code-block:: yaml + + Release: + name: '📦 Release' + runs-on: ubuntu-latest + needs: + - ... + if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/master' || contains(github.ref, 'refs/tags/'>`__) + steps: + + - uses: actions/download-artifact@v2 + + - shell: bash + run: pip install PyGithub --progress-bar off + + - name: Set list of files for uploading + id: files + shell: python + run: | + from github import Github + print("· Get GitHub API handler (authenticate)") + gh = Github('${{ github.token }}') + print("· Get Repository handler") + gh_repo = gh.get_repo('${{ github.repository }}') + +Find a non-trivial use case at `msys2/msys2-autobuild `__. diff --git a/doc/Action/With-post-step.rst b/doc/Action/With-post-step.rst index 5e4154b..6ab3d98 100644 --- a/doc/Action/With-post-step.rst +++ b/doc/Action/With-post-step.rst @@ -1,3 +1,5 @@ +.. _ACTION/WithPostStep: + with-post-step ############## diff --git a/doc/JobTemplate/Parameters.rst b/doc/JobTemplate/Parameters.rst index b165a3a..8e0a3b4 100644 --- a/doc/JobTemplate/Parameters.rst +++ b/doc/JobTemplate/Parameters.rst @@ -190,9 +190,9 @@ Results Params ====== +.. todo:: Parameters:Params Needs documentation. Jobs ==== - - +.. todo:: Parameters:Jobs Needs documentation. diff --git a/doc/index.rst b/doc/index.rst index 6f1ca01..27d2adc 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -69,9 +69,33 @@ GitHub Action Job Templates * :ref:`JOBTMPL/ArtifactCleanup` +Example Pipelines +================= + +``ExamplePipeline.yml`` is an example Workflow which uses all of the Reusable Workflows. +Python package/tool developers can copy it into their repos, in order to use al the reusable workflows straightaway. +Minimal required modifications are the following: + +- Set the ``name`` input of job ``Parameters``. +- Specify the ``commands`` input of job ``StaticTypeCheck``. + +Find further usage cases in the following list of projects: + +- `edaa-org/pyEDAA.ProjectModel `__ +- `edaa-org/pySVModel `__ +- `VHDL/pyVHDLModel `__ + + GitHub Actions ************** +* :ref:`ACTION/Releaser` +* :ref:`ACTION/WithPostStep` + +References +********** + +- `hdl/containers#48 `__ Contributors ************