Skip to content

GitHub Actions

GitHub Actions ⧉ are used to run CI/CD pipelines.

Important

No pipeline modifies the repository contents (e.g. no formatting is done), it only verifies the compliance (e.g. linting) of source code.

Pipelines

Note

Configuration is stored in .github directory and .github/workflows specifically

Pipelines run approximately the same steps as pre-commit hooks, the specific tooling functionality is located in various other documents such as legal, python, other languages, prose, etc.

Features of note include:

  • each workflow starts with a semantic prefix defining its purpose (e.g. tests, security, docs)

  • most of the workflows from each semantic group comes in three flavors:

    • <type>.yml - analogous to check/linter of type, done for every push to the pull request (usually ran only if files of interest where changed in the pull request, e.g. **.md files for markdown.yml
    • <type>-renovate.yml - checks run, when renovate[bot] makes an update to the checkers (e.g. dev-markdown in pyproject.toml's [dependency-groups] gets updated, the markdown checks run on all markdown files in the repository). This allows verification of updates against currently accepted standards (e.g. no new checks were introduced without feedback)
    • <type>-reusable.yml - de facto implementation of the linter, will be called <type>.yml and <type>-renovate.yml

  • *-update.yml workflows are ran periodically, see scheduled jobs documentation for more details

Note

This structure may not be present in all workflows, as some checks should not be ran on every push or renovate update, in these cases only <type>.yml might be present.

Reusable workflows

Reusable workflows ⧉:

  • Improve security (as the source code is not modifiable by the repository owner)
  • Streamline updates from the main template (as the reusable workflows are updated from the opennudge/opentemplate repository)

You might want to change the reusable workflows to local workflows if you:

  • want to fully control your pipelines
  • want to host/adjust the pipeline yourself
  • do not want the pipelines to change behavior without your consent

If so, check the configuration section.

Special workflows

These workflows might be of special interest:

  • check-run-reusable.yml - runs most of the checks defined in <type>-reusable.yml as a sort of centralized runner
  • security-* - ran on PRs and periodically to ensure the security of the project, see security section for more details

Caching

Centralized caching (create from main branch) is used for all workflows, after PR merge, the cache is updated (if needed) and stored.

Note

Cache is optimized on a per-workflow basis, each having a minimal set of necessary dependencies.

Tip

For source code check cache.yml

Configuration

Important

Many of the features can be controlled via pyproject.toml as described in configuration section.

Changing workflows reusability

Scripts provided in .github/workflows/reusability:

  • localize.sh - changes the reusable workflows (pointing to opennudge/opentemplate) to local workflows
  • globalize.sh - changes the local workflows to reusable workflows (pointing to opennudge/opentemplate)

Run ./reusability/localize.sh or ./reusability/globalize.sh to apply the changes. The script also allows you to specify the directory where the changes should be applied as an argument.

Caution

While localize.sh is safe to run, globalize.sh should be used with caution, as it may incorrectly globalize local workflows/actions you have added on top of the template provided functionality.

Warning

release-package-reusable.yml and release-package-upload-reusable.yml used by release.yml should not be globalized as they are attested uploads to PyPI do not yet support reusable workflows (see this GitHub issue ⧉).

Code sources

  • pyproject.toml
  • .github/workflows/*.yml
  • .github/actions/*/action.yml