CI/CD Pipeline

This guide covers the continuous integration (CI) pipeline used in HERITRACE to ensure code quality and automate testing.

GitHub Actions workflows

HERITRACE uses GitHub Actions for continuous integration and release automation. The project includes two main workflows:

1. Testing Workflow (.github/workflows/python-tests.yml): Triggered on every push to any branch and on pull requests to the main branch
2. Release Workflow (.github/workflows/release.yml): Triggered on pushes to main branch containing [release] in the commit message

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. It is triggered when a commit to the main branch contains [release] in the commit message.

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