Automations

A number of automations are available to facilitate the development, deployment and documentation of the service. Here we describe the ones that are directly, publicly available.

Dockerfile

The main delivery package for the service is a docker image. The Dockerfile at the root of the code repository builds the Docker image. Dependencies are installed with uv from the committed uv.lock, so the image always contains the exact dependency versions that were tested.

Docker image publishing

A GitHub Action workflow is available to build and publish the docker image for the service. The action is triggered when a new tag matching v* is pushed to the repository. This way, all the images produced are always named and can be traced back to the codebase snapshot that generated them.

The generated docker image is pushed to the GitHub organization Packages using the name of the service repo and the version tag that triggered the execution.

Documentation

A GitHub Action workflow is available to generate the documentation presented here. The action is triggered manually and runs against the head of the repository. The documentation generated is versioned and the documentation version is expected as input to the workflow.

The documentation is built using the mkdocs library and specifically using the Material for mkdocs theme. A number of additional tools are utilized, such as mike to support versioning and neoteroi.mkdocsoad to support OpenAPI specification rendering.

The documentation is generated and tagged with the provided version, which is also aliased as latest. It is uploaded to a dedicated documentation branch that the repository GitHub Page presents its contents from.

The OpenAPI Reference is rendered from the openapi.json file kept with the documentation. When the Api changes, this file should be refreshed from a running instance (/api/v1/openapi.json) before publishing a new documentation version.