Skip to content

Github Automations

This repository leverages the automation provided by Github actions for automatically building and deploying the documentation to Github pages.

The caller actions can be found in the .github/workflows folder of this repository while the re-usable workflows, which contains the actual steps performed by the actions, are available at https://github.com/eurotech/add-ons-automation. This allows for easier maintenance of the actions since they're shared among a lot of different repositories.

The caller actions are the following:

  • backport.yml: Backport automation action. For the re-usable workflow called by this action see here.
  • build-deploy-docs.yml: Documentation build and deploy automation action. For the re-usable workflow called by this action see here.
  • pr-lint.yml: GitHub Action that ensures PR titles matche the Conventional Commits specification. For the re-usable workflow called by this action see here.

Some more details about the automations can be found in the following paragraphs.

Building and deploying

The Github "Build and deploy" is responsible for building the documentation sources and deploying them on the gh-pages branch.

The action expects the documentation for the latest version of the software to be on its own branch named docs-develop. Older, already released versions, should stay on docs-release-[major].[minor] named branches (which should be child branches of docs-develop). For example we expect to see the following branches on a repository:

$ git branch --list "docs*"
docs-develop
docs-release-5.1
docs-release-5.1

The Github action will use the branch name for determining and deploying the documentation to its respective version.

Whenever a change on docs-develop and docs-release-* branches is detected the Github action will kick-off, installing the dependencies listed in the requirements.txt file, building the documentation and deploying it to gh-pages leveraging mike.

After that the pages-build-deployment action will take care of serving the page on Github pages.

Warning

The automation expects the requirements.txt file to contain the mkdocs, mike and mkdocs-material package version to be installed and any additional plugin for mkdocs used by the documentation.

Backport automation

Given the branch-based nature of the "Build & deploy documentation" action, it lends itself well to the "Backport" workflow of commits.

Whenever a change on the docs-develop branch (which should contain the documentation for the latest version of the software) needs to be ported on the older release we can leverage the "Backport" automation.

To trigger the backport, after opening a PR it is sufficient to add a label to the PR. The label should be named backport docs-release-[major].[minor] where [major] and [minor] identify the target branch for the backport.

Here's an example:

Github backport label example

After a few seconds a bot will open a new PR to the target branch with the desired changes.