CCPBioSim Shared Infrastructure

Shared defaults for CCPBioSim software projects: consistent dependency management, community-health files, and reusable CI, release and maintenance workflows.

Centralising maintenance does not require centralising every decision. Policy and repeated mechanics are shared. Scientific decisions stay in each package repository: dependency floors, supported Python versions, package paths, conda recipes and release exceptions.

flowchart LR
    A["CCPBioSim/.github<br/>shared defaults"] --> B["Renovate presets"]
    A --> C["Community-health defaults"]
    A --> D["Reusable workflows"]
    B --> R["Package repositories"]
    C --> R
    D --> R

    style A fill:#245b78,color:#ffffff,stroke:#245b78

Renovate. Add a small .github/renovate.json to a repository:

{
  "extends": [
    "github>CCPBioSim/.github//renovate/default",
    "github>CCPBioSim/.github//renovate/python"
  ],
  "assignees": ["<maintainer>"]
}

Changes here reach every repository on its next Renovate run. Runtime dependencies, dev tools and GitHub Actions are each grouped, and every pull request carries the dependencies label alongside ci, python, production-deps or dev-dependencies.

Community-health files. Nothing to do. GitHub inherits them for repositories without their own copy, and a local file always wins.

Finding dependency updates across the organisation:

org:CCPBioSim is:pr is:open label:dependencies

Reusable workflows live in .github/workflows/. The folder is nested because this repository is itself called .github, so a caller writes the name twice:

uses: CCPBioSim/.github/.github/workflows/<name>.yaml@<full commit SHA> # X.Y.Z

Callers pin a full commit SHA with the version in a trailing comment, so Renovate can propose updates. A called workflow cannot have more permissions than its caller, so a caller grants what the table lists. Triggers, schedules and concurrency stay in the caller.

Coverage is measured on one leg only, the first runner in os on coverage-python-version, or on the first entry of python-versions when that version is not in the list. That leg saves coverage.xml as an artifact, and the Coverage job uploads it to Coveralls, so the other legs run without the coverage overhead. Coverage is on by default in ci-test-python and off in ci-test-conda, so a conda-based caller sets coverage: true where it wants a report. A caller that runs a test workflow from a matrix gives each leg its own coverage-flag and closes the build with ci-coveralls-finish, so the reports have distinct names and combine in Coveralls.

ci-test-cpp-coverage measures C++ coverage for packages with compiled code. It installs the package, and any conda-packages the tests need, runs build-command to build the instrumented code, runs pytest, and uploads the C++ report through the actions/cpp-coverage-upload composite action. To report combined coverage, a caller sets coverage-flag on ci-test-python or ci-test-conda, runs ci-test-cpp-coverage alongside it, and closes the build with ci-coveralls-finish once both have finished. Do this on pull requests as well as on main, so Coveralls compares the same total. ci-test-python and ci-test-conda take pre-test-command, and ci-docs takes pre-build-command, for steps that must run first, such as downloading data or generating files. The release workflows also take dry-run, which runs every step except the ones that publish or change the repository.

Workflows in this repository are audited with zizmor through pre-commit, which runs in CI through ci-pre-commit.

A package repository's pr.yaml looks like this:

name: Pull Request CI

on:
  pull_request:

permissions:
  contents: read

concurrency:
  group: pr-ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  unit:
    name: Unit
    uses: CCPBioSim/.github/.github/workflows/ci-test-python.yaml@<sha> # X.Y.Z
    permissions:
      contents: read
      checks: write
      statuses: write
    with:
      package: mypackage
      lowest-dependencies-check: true
  docs:
    name: Docs
    needs: unit
    uses: CCPBioSim/.github/.github/workflows/ci-docs.yaml@<sha> # X.Y.Z
    permissions:
      contents: read
  pre-commit:
    name: Pre-commit
    needs: unit
    uses: CCPBioSim/.github/.github/workflows/ci-pre-commit.yaml@<sha> # X.Y.Z
    permissions:
      contents: read

The defaults in the shared workflows are the organisation baseline. Checks that validate compatibility run the full supported Python set by default. Checks that validate presentation run one leg by default. A repository widens or narrows these explicitly in its own workflow, and each exception is its own choice to document.

Python versions. The default set is the three newest stable CPython releases. A package's own pyproject.toml is the source of truth, so its matrix should match its requires-python and classifiers. A package with a narrower range overrides the default in its workflow. Adding a Python version waits until the package's dependencies support it, and dropping one is a deliberate, reviewed change.

Operating systems. The default is Linux only, on ubuntu-26.04. Add macOS and Windows where a package has platform-specific behaviour, such as native code, numerical libraries or documented platform support. A scheduled workflow can run the wider matrix so pull requests stay quick.

The runner label is written as a literal runs-on in some workflows, which Renovate updates, and in the os defaults, which it cannot see. When Renovate proposes a runner update, change the os defaults in the same pull request. grep -rn "ubuntu-" .github lists every place.

Every package repository uses the same set of caller workflows. Start from Python-Template, which has the full set, and see CodeEntropy for a pip-based package and aiida-amber for a conda-based one.

Python versions come from the shared defaults, so the files list none unless requires-python is narrower. A conda-based package adds conda-packages for the programs pip cannot install, and a package that needs an extra matrix axis puts a normal strategy.matrix on the calling job. Workflows that only one package needs, such as regression tests or a Docker image build, stay in that repository next to these files.

Branch protection requires the checks from pr.yaml. Their names come from the job and workflow names, for example Unit / Test (ubuntu-26.04, py3.14), so update the required checks when a matrix or job name changes.

Dependency floors. Set lowest-dependencies-check: true on the test job. After the normal tests, each leg reinstalls the lowest versions pyproject.toml allows for its direct dependencies and runs the tests again, so the floors are checked on every OS and Python version without extra jobs. Coverage is measured only in the normal run. weekly-tests.yaml runs it too, so no separate floors workflow is needed.

_{Maintained by the CCPBioSim community.}