CI/CD pipeline

This guide covers the continuous integration (CI) pipeline used in HERITRACE for automated checks, documentation deployment, releases, and citation updates.

GitHub Actions workflows

HERITRACE uses separate GitHub Actions workflows so that each check has its own status and README badge:

• Run tests (.github/workflows/python-tests.yml) runs the test matrix and deploys the documentation and coverage report to GitHub Pages.
• Pyright (.github/workflows/pyright.yml) checks Python types.
• Ruff (.github/workflows/ruff.yml) checks linting and formatting.
• REUSE compliance (.github/workflows/reuse.yml) checks licensing metadata.
• Release (.github/workflows/release.yml) creates the release and publishes container images after all four checks succeed.
• Software citation (.github/workflows/software-citation.yml) updates citation metadata after a successful release.

The first four workflows run independently on every push and on pull requests to main. On main, Release starts when Run tests completes. It proceeds only when that workflow succeeds, the commit message contains [release], and the Pyright, Ruff, and REUSE push runs for the same commit also succeed.

Testing workflow steps

The CI pipeline performs the following steps:

1. Set up Python: Tests against multiple Python versions (3.10, 3.11, 3.12, 3.13) to ensure compatibility.
2. Install dependencies: Uses uv to install project dependencies, including development dependencies.
3. Run tests: Executes the test suite using pytest with coverage. Test databases start automatically via the docker_services pytest fixture.
4. Upload coverage report: On the main branch (Python 3.10 only), the HTML coverage report and badge are uploaded as build artifacts.
5. Deploy to GitHub Pages: A separate job builds the documentation site, downloads the coverage artifacts, and deploys everything to GitHub Pages.

Coverage badge

The workflow uses genbadge to generate an SVG badge from coverage.xml. The badge and HTML report are deployed to GitHub Pages alongside the documentation.

Release workflow

The release workflow automates the creation of releases and publication of Docker images. A commit on main is eligible when its message contains [release]; publication starts only after the workflow gates described above succeed for that commit.

Release workflow steps

1. Semantic Release: Uses semantic-release to automatically create GitHub releases based on conventional commit messages
2. Docker Image Building: Builds multi-platform Docker images (AMD64 and ARM64)
3. Docker Hub Publishing: Publishes images to Docker Hub under the configured username
4. GitHub Container Registry: Publishes images to GitHub Container Registry (ghcr.io)

Required secrets

To enable Docker publishing, the following secrets must be configured in your GitHub repository:

• DOCKER_HUB_USERNAME: Your Docker Hub username
• DOCKER_HUB_ACCESS_TOKEN: Docker Hub access token for authentication

The workflow automatically uses the GITHUB_TOKEN for GitHub Container Registry authentication.

Docker image tags

The workflow generates the following tags:

• latest: For the main branch
• Version tag (e.g. 1.0.0): The semantic version

Published images

Images are published to:

• Docker Hub: [username]/heritrace
• GitHub Container Registry: ghcr.io/[owner]/[repository]

Customizing the workflows

You can customize the workflows by editing the respective files:

• .github/workflows/python-tests.yml for testing configuration
• .github/workflows/release.yml for release and Docker publishing