Skip to content

About

A centralized repo for reusable GitHub workflows

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

32 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 

Repository files navigation

gh_workflows

Reusable GitHub Actions workflows for stajichlab repositories.

Workflows in this repo

Shared (call these from other repos with uses: stajichlab/gh_workflows/.github/workflows/<file>@v2):

Workflow Purpose
release_prepare Bump the version and open a release pull request
release_publish Tag a merged release PR and create the GitHub release
sync_dev Merge the release into the development branch
container_build Build, smoke-test and push a container image
container_cleanup Delete old untagged GHCR image versions without breaking tagged images
pixi_lock_refresh Refresh pixi.lock on Dependabot PRs
changelog_check Require a changelog entry on PRs
citation_check Validate CITATION.cff
python_test_pip / _conda / _pixi Run Python tests with pip, conda or pixi
bioconda_recipe_check Fail (red badge) when the repo's conda recipe differs from bioconda's
bioconda_recipe_solve Check a noarch Python recipe's run requirements install on every supported Python

Note

For this repo only, not for callers: release.yml, publish.yml, changelog.yml, lint.yml and the test_*.yml workflows. They have no workflow_call trigger, so other repos cannot call them. They release, check and test gh_workflows itself; see Releasing this repo and Development.

release_prepare

Computes the next version from the latest v* tag, checks it against CHANGELOG.md (Keep a Changelog format) if the repo has one, bumps the changelog, runs the calling repo's own version bump command, updates and validates CITATION.cff if present (warning if it is missing), commits to a release/v<version> branch and opens a pull request for review. Tagging, building and publishing are left to the caller (for example, a workflow triggered when the release PR is merged).

Version source. Tags are the source of truth: the previous version is the highest semver among v* tags reachable from base_branch (0.0.0 if there are none), and the next one is derived from it with bump_type/preid. If a changelog exists, its latest release must equal the latest tag, otherwise the workflow fails; the changelog is then bumped to the tag-derived version. Without a changelog, the PR lists commit subjects since the last tag instead.

The workflow also fails early if the tag or the release/v<version> branch already exists.

The version bump is supplied by the caller through additional_bump_command, so each repo decides which files carry the version. The new version is available as $VERSION.

Use it when

  • You want releases to go through a reviewed pull request instead of tagging by hand.
  • The version should come from git tags, with CHANGELOG.md and CITATION.cff kept in step automatically.
  • Each repo stores its version somewhere different (pyproject.toml, __init__.py, an R DESCRIPTION file, ...) and needs its own small bump command.
  • You publish release candidates (1.3.0-rc.0) before a final release, or patch an older release line.

Examples

Minimal: manual release with a bump-type menu. Run it from Actions → Release; it opens a Release v<version> PR.

# .github/workflows/release.yml
name: Release
on:
  workflow_dispatch:
    inputs:
      bump_type:
        description: Version bump type
        type: choice
        options: [patch, minor, major, prepatch, preminor, premajor, prerelease]
      preid:
        description: Prerelease identifier (e.g. rc)
        type: string

jobs:
  prepare:
    uses: stajichlab/gh_workflows/.github/workflows/release_prepare.yml@v2
    permissions:
      contents: write
      pull-requests: write
    with:
      bump_type: ${{ inputs.bump_type }}
      preid: ${{ inputs.preid }}

Python package with a fallback version in pyproject.toml (as in Phyling), with reviewers requested and a token so the release PR runs CI:

jobs:
  prepare:
    uses: stajichlab/gh_workflows/.github/workflows/release_prepare.yml@v2
    permissions:
      contents: write
      pull-requests: write
    with:
      bump_type: ${{ inputs.bump_type }}
      preid: ${{ inputs.preid }}
      reviewers: some-user,stajichlab/some-team
      additional_bump_command: |
        sed -i "s/^default-version = .*/default-version = \"$VERSION\"/" pyproject.toml
        grep -q "^default-version = \"$VERSION\"" pyproject.toml
    secrets:
      token: ${{ secrets.RELEASE_TOKEN }}

Version in several files (a Python __init__.py and an R DESCRIPTION). Ending with grep -q checks makes the run fail if a file didn't contain the expected line:

    with:
      bump_type: ${{ inputs.bump_type }}
      additional_bump_command: |
        sed -i "s/^__version__ = .*/__version__ = \"$VERSION\"/" src/mytool/__init__.py
        sed -i "s/^Version: .*/Version: $VERSION/" DESCRIPTION
        grep -q "^__version__ = \"$VERSION\"" src/mytool/__init__.py
        grep -q "^Version: $VERSION$" DESCRIPTION

Patch an older release line from a maintenance branch. Only tags on that branch count, so patch after v1.4.2 gives 1.4.3 even if main is already at 2.x:

    with:
      bump_type: patch
      base_branch: v1.x

Release candidates. preminor with preid: rc turns 1.2.0 into 1.3.0-rc.0. Later runs with prerelease give 1.3.0-rc.1, and a final patch run gives 1.3.0.

Reference

Input Default Description
bump_type (required) major, premajor, minor, preminor, patch, prepatch or prerelease
preid "" Prerelease identifier
additional_bump_command "" Shell command that updates version strings; runs with $VERSION set
changelog_path CHANGELOG.md Changelog location; skipped if missing
base_branch main Branch to release from and PR target
draft false Open the PR as a draft
reviewers "" Comma-separated users or org/team slugs to request review from
Secret Description
token Optional GitHub App token or PAT (contents and pull requests: write). PRs opened with the default GITHUB_TOKEN don't trigger the repo's CI; pass this to get CI checks on the release PR. Requesting team reviewers may also need it.

Outputs: version, previous_version, release_notes, prerelease ('true'/'false'), pr_url.

Calling repos must enable Settings → Actions → General → Allow GitHub Actions to create and approve pull requests.

If this repo is private, allow access from other org repos under Settings → Actions → General → Access.

If a step fails after the release branch was pushed, the branch is deleted so the run can simply be retried.

Only one release_prepare run per repository proceeds at a time. A second run waits; if a third is started while one is waiting, GitHub cancels the waiting one.

release_publish

The other half of release_prepare. When a release/v<version> pull request is merged, it tags the merge commit on the base branch as v<version> (where the next release_prepare run will find it), creates the GitHub release and deletes the release branch. Release notes come from the changelog entry for that version, or are generated by GitHub if there is no changelog. Versions with a prerelease suffix (1.3.0-rc.0) are marked as prereleases and never as the latest release. Files from an artifact built earlier in the calling run can be attached.

It does nothing (and outputs published: 'false') unless the triggering PR was merged from a release/v* branch, so it is safe to call on every closed PR.

Use it when

  • You use release_prepare and need the merged release PR turned into a tag and a GitHub release.
  • You want built files (an sdist, wheels, binaries) attached to the GitHub release.
  • Publishing should wait for a maintainer's approval.
  • A publish run failed partway and needs to be re-run by hand.

Examples

Minimal: tag and release on merge. Safe to run on every closed PR; it only publishes merged release/v* PRs.

# .github/workflows/publish.yml
name: Publish
on:
  pull_request:
    types: [closed]
    branches: [main]

jobs:
  publish:
    uses: stajichlab/gh_workflows/.github/workflows/release_publish.yml@v2
    permissions:
      contents: write

Full pipeline: build, publish with files attached, then container and dev sync. Repo-specific jobs (build) stay in the repo; shared ones are chained with needs: so they run after the tag exists.

name: Publish
on:
  pull_request:
    types: [closed]
    branches: [main]

jobs:
  build:
    if: github.event.pull_request.merged && startsWith(github.head_ref, 'release/v')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - run: pipx run build --sdist
      - uses: actions/upload-artifact@v7
        with:
          name: dist
          path: dist/

  publish:
    needs: build
    uses: stajichlab/gh_workflows/.github/workflows/release_publish.yml@v2
    permissions:
      contents: write
    with:
      artifact: dist

  container:
    needs: publish
    if: needs.publish.outputs.published == 'true'
    uses: stajichlab/gh_workflows/.github/workflows/container_build.yml@v2
    permissions:
      contents: read
      packages: write
    with:
      ref: ${{ needs.publish.outputs.tag }}

  sync-dev:
    needs: publish
    if: needs.publish.outputs.published == 'true'
    uses: stajichlab/gh_workflows/.github/workflows/sync_dev.yml@v2
    permissions:
      contents: write
      pull-requests: write

Require approval before publishing. Create a release environment with required reviewers under Settings → Environments, then:

  publish:
    uses: stajichlab/gh_workflows/.github/workflows/release_publish.yml@v2
    permissions:
      contents: write
    with:
      environment: release

Re-publish by hand after a failed run. Start it from main so the commit it runs on is the release commit (or pass target); the tag is reused if it already exists on that commit:

# .github/workflows/publish-manual.yml
name: Publish (manual)
on:
  workflow_dispatch:
    inputs:
      version:
        description: Version to publish (e.g. 1.3.0)
        required: true

jobs:
  publish:
    uses: stajichlab/gh_workflows/.github/workflows/release_publish.yml@v2
    permissions:
      contents: write
    with:
      version: ${{ inputs.version }}
      delete_branch: false

Reference

Input Default Description
version from release/v<version> Version to publish
target PR merge commit (github.sha if version is given) Commit to tag
changelog_path CHANGELOG.md Changelog location; GitHub-generated notes if missing
artifact "" Artifact from the calling run whose files are attached
environment "" Deployment environment for the publish job, e.g. to require approval
delete_branch true Delete release/v<version> afterwards
Secret Description
token Optional GitHub App token or PAT. Tags and releases created with GITHUB_TOKEN don't trigger other workflows (push: tags, release: published); pass this if anything relies on those triggers.

Outputs: published, version, tag, prerelease, release_url.

Requiring approval. Pass environment: release (any name) and, in the calling repo, configure that environment under Settings → Environments with required reviewers. The publish job then waits for approval before tagging. The workflow only names the environment; the approval rule lives in each repo's settings, and GitHub creates an unconfigured environment (no approval) if it doesn't exist yet. A token secret stored in that environment is used in place of one passed by the caller, so it is only available to approved runs.

sync_dev

Brings the development branch (dev) up to date with the release branch (main) after a release. It merges main into dev and pushes; if dev already contains main it does nothing. If the merge conflicts or the push is rejected (for example by branch protection on dev), it pushes main's commit to a sync/main-to-dev-<sha> branch and opens a pull request into dev instead, so conflicts are resolved on that branch and never on main. Re-running while that PR is open reuses it.

Use it when

  • Your repo develops on dev (or develop) and releases from main, and dev should pick up the release commit (version bump, changelog) right after each release.
  • Fixes made on main during a release must not be lost on dev.
  • dev is protected, so updates must arrive as a pull request.

Examples

After publishing (recommended). Chain it after release_publish so it runs as soon as the release exists:

jobs:
  publish:
    uses: stajichlab/gh_workflows/.github/workflows/release_publish.yml@v2
    permissions:
      contents: write

  sync-dev:
    needs: publish
    if: needs.publish.outputs.published == 'true'
    uses: stajichlab/gh_workflows/.github/workflows/sync_dev.yml@v2
    permissions:
      contents: write
      pull-requests: write

Different branch names, with reviewers for the fallback PR:

  sync-develop:
    uses: stajichlab/gh_workflows/.github/workflows/sync_dev.yml@v2
    permissions:
      contents: write
      pull-requests: write
    with:
      source_branch: master
      target_branch: develop
      reviewers: some-user

On a published release, or by hand. release: published only fires if the release was created with a token other than GITHUB_TOKEN:

# .github/workflows/sync-dev.yml
name: Sync dev
on:
  release:
    types: [published]
  workflow_dispatch:

jobs:
  sync-dev:
    uses: stajichlab/gh_workflows/.github/workflows/sync_dev.yml@v2
    permissions:
      contents: write
      pull-requests: write

Reference

Input Default Description
source_branch main Branch that received the release
target_branch dev Branch to bring up to date
reviewers "" Reviewers to request if a PR is opened
Secret Description
token Optional GitHub App token or PAT. Needed if pushes to dev should trigger CI, or if dev is protected and the token is allowed to bypass that protection.

Outputs: result (up-to-date, merged or pull-request), pr_url.

container_build

Builds a container image from a branch, tag or commit, runs an optional smoke test against the locally loaded image, then pushes it (to GHCR by default). Tags:

Tag When
1.2.3 a version is given, or ref looks like v1.2.3
1.2 same, but not for prereleases
latest a stable version (not a prerelease), unless latest: false
sha-<short sha> always; the commit that was built (ref), not the one that triggered the caller
extra tags from extra_tags

Use it when

  • Your tool ships a container image and every release should publish a matching, versioned image.
  • You want a test image from a branch without making a release.
  • PRs that touch the Dockerfile should prove the image still builds and runs, without pushing anything.
  • You need multi-architecture images or a registry other than GHCR.
  • You want pushed images signed with Cosign (sign: true), the same way across repos.

Examples

Release image, after release_publish. Tags 1.2.3, 1.2, latest and sha-...; a prerelease gets only its exact version:

  container:
    needs: publish
    if: needs.publish.outputs.published == 'true'
    uses: stajichlab/gh_workflows/.github/workflows/container_build.yml@v2
    permissions:
      contents: read
      packages: write
    with:
      ref: ${{ needs.publish.outputs.tag }}
      smoke_test_args: --help

Test image from any branch, by hand:

# .github/workflows/container-test.yml
name: Container (test image)
on:
  workflow_dispatch:
    inputs:
      tag:
        description: Image tag to publish
        default: testing

jobs:
  container:
    uses: stajichlab/gh_workflows/.github/workflows/container_build.yml@v2
    permissions:
      contents: read
      packages: write
    with:
      ref: ${{ github.ref_name }}
      extra_tags: ${{ inputs.tag }}
      smoke_test_args: --help

Build check on pull requests (builds and smoke-tests, never pushes):

# .github/workflows/container-check.yml
name: Container check
on:
  pull_request:
    paths: [Dockerfile, .dockerignore, pyproject.toml]

jobs:
  container:
    uses: stajichlab/gh_workflows/.github/workflows/container_build.yml@v2
    permissions:
      contents: read
      packages: write
    with:
      push: false
      smoke_test_args: --version

Multi-architecture image on Docker Hub, with a build argument:

  container:
    needs: publish
    if: needs.publish.outputs.published == 'true'
    uses: stajichlab/gh_workflows/.github/workflows/container_build.yml@v2
    permissions:
      contents: read
      packages: write
    with:
      ref: ${{ needs.publish.outputs.tag }}
      image: docker.io/stajichlab/mytool
      platforms: linux/amd64,linux/arm64
      build_args: |
        CONDA_ENV=environment.yml
    secrets:
      registry_username: ${{ secrets.DOCKERHUB_USERNAME }}
      registry_password: ${{ secrets.DOCKERHUB_TOKEN }}

Signed release image. Keyless Cosign signing needs an OIDC token, so the caller must grant id-token: write as well as packages: write:

  container:
    needs: publish
    if: needs.publish.outputs.published == 'true'
    uses: stajichlab/gh_workflows/.github/workflows/container_build.yml@v2
    permissions:
      contents: read
      packages: write
      id-token: write
    with:
      ref: ${{ needs.publish.outputs.tag }}
      sign: true

Only the pushed image index is signed (no --recursive), as in GitHub's Docker publish starter workflow: signing each platform and attestation manifest would add a sha256-<digest> signature tag apiece to the package. Tags resolve to the index, so verify with the command below. The signature is annotated with the publish's sha- tag (sha=sha-abc1234); add -a sha=sha-abc1234 to require it.

cosign verify \
  --certificate-identity-regexp 'https://github.com/<owner>/<repo>/.github/workflows/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/<owner>/<repo>:1.2.3

Reference

Input Default Description
ref triggering commit Branch, tag or commit to build
version from ref if it is v<semver> Version tag
image ghcr.io/<owner>/<repo> (lowercased) Image name without tag
context . Build context
dockerfile Dockerfile Dockerfile path
build_args "" Newline-separated NAME=value
platforms linux/amd64 Platforms to push; QEMU is set up for anything else
smoke_test_args "" Arguments for docker run --rm <image>; skipped if empty
latest true Tag stable versioned builds as latest; never prereleases or unversioned builds
extra_tags "" Newline-separated extra tags
push true Push; if false, only build and smoke-test
sign false Sign the pushed index with keyless Cosign; only with push. Caller must grant id-token: write and packages: write
Secret Description
registry_username, registry_password For registries other than GHCR (e.g. Docker Hub). GHCR uses GITHUB_TOKEN.

Outputs: image, tags, digest, signature (the index's signature tag, e.g. sha256-<hex>; empty if not signed).

The checkout includes full history and tags, so version tools such as versioningit or setuptools-scm work during the build (the .git directory must not be excluded by .dockerignore for that). The first push of a new GHCR image creates it as private; change its visibility in the package settings.

Builds of the same ref queue one at a time (they share a concurrency group, so two builds never push the same tags at once). GitHub keeps only one pending run per group: if a third build of that ref queues while one runs and one waits, the waiting one is cancelled. Chain such builds with needs: instead of starting them together.

container_cleanup

Deletes untagged versions of GHCR container packages that have not been updated for min_age_days (180 by default). Every push leaves untagged versions behind: the previous image when a tag such as latest moves, and the per-platform and buildx attestation manifests of every image. This removes the old ones safely:

  • Tagged images stay complete. GHCR lists each platform and attestation manifest of a multi-arch image as its own untagged version, often older than the cutoff. The manifests of all tagged versions, and of untagged versions younger than the cutoff, are read, and everything they reference is kept.
  • Signatures follow their image. A Cosign signature tag (sha256-<digest>) is kept while its image is kept, and deleted with it (or when the image is already gone). Untagged artifacts attached to a kept image through the OCI subject field are kept too.
  • Fails closed. If a manifest cannot be read, or a tagged version is missing from the registry, the job fails before deleting anything. Untagged versions and child manifests that GHCR lists or references but no longer serves are reported as warnings and never deleted.

The step summary lists every deleted (or, with dry_run: true, would-be deleted) version. GHCR only; deleted versions of organization packages can be restored for 30 days in the package settings.

Use it when

  • latest or other moving tags leave a growing list of untagged versions on the package page.
  • You publish multi-arch or signed images, so a plain "delete untagged" cleanup would break them.

Examples

Weekly cleanup of the repo's image (ghcr.io/<owner>/<repo>):

# .github/workflows/container-cleanup.yml
name: Container cleanup
on:
  schedule:
    - cron: "0 6 * * 1"
  workflow_dispatch:

jobs:
  cleanup:
    uses: stajichlab/gh_workflows/.github/workflows/container_cleanup.yml@v2
    permissions:
      contents: read
      packages: write

Several packages, previewed first:

jobs:
  cleanup:
    uses: stajichlab/gh_workflows/.github/workflows/container_cleanup.yml@v2
    permissions:
      contents: read
      packages: write
    with:
      packages: |
        mytool
        mytool-gpu
      min_age_days: 90
      dry_run: true

Reference

Input Default Description
packages repo name (lowercased) Newline-separated GHCR container package names
min_age_days 180 Delete untagged versions not updated for at least this many days
dry_run false Only list what would be deleted

The calling repo's GITHUB_TOKEN must have admin access to each package: packages first pushed by the repo's own workflows have it; for others, add the repo under Manage Actions access in the package settings with the Admin role.

pixi_lock_refresh

Dependabot bumps dependencies in pyproject.toml / pixi.toml but does not update pixi.lock. This regenerates the lock file on the pull request branch and pushes it, so the PR stays installable with pixi install --locked. It does nothing if the lock file is already current, and by default only acts on Dependabot PRs from the same repository.

Use it when

  • Your repo uses pixi with a committed pixi.lock, and Dependabot updates dependencies in pyproject.toml or pixi.toml.
  • CI installs with --locked (as python_test_pixi always does), so Dependabot PRs fail until the lock file is regenerated.

Examples

Basic: refresh on Dependabot PRs.

# .github/workflows/pixi-lock.yml
name: Refresh pixi.lock
on:
  pull_request:
    paths: [pyproject.toml, pixi.toml]

jobs:
  refresh:
    uses: stajichlab/gh_workflows/.github/workflows/pixi_lock_refresh.yml@v2
    permissions:
      contents: write   # Dependabot runs get a read-only token unless the caller grants write

Manifest in a subdirectory, pixi version pinned, and a token so CI re-runs on the lock-file commit (store PIXI_LOCK_TOKEN under Settings → Secrets and variables → Dependabot):

name: Refresh pixi.lock
on:
  pull_request:
    paths: [analysis/pixi.toml]

jobs:
  refresh:
    uses: stajichlab/gh_workflows/.github/workflows/pixi_lock_refresh.yml@v2
    permissions:
      contents: write
    with:
      working_directory: analysis
      pixi_version: v0.50.0
    secrets:
      token: ${{ secrets.PIXI_LOCK_TOKEN }}

Any same-repo PR, not just Dependabot (for contributors who edit dependencies without re-locking):

    with:
      dependabot_only: false

Reference

Input Default Description
working_directory . Directory with the manifest and pixi.lock
pixi_version latest pixi version to install
dependabot_only true Only act on Dependabot PRs
Secret Description
token Optional GitHub App token or PAT. Workflows triggered by Dependabot can only read Dependabot secrets, so store it there.

Outputs: updated.

Things to know.

  • A push made with GITHUB_TOKEN does not trigger workflows, so the PR's CI does not rerun on the lock-file commit. If CI checks are required for merging, pass token, or the PR waits on checks that never run for its latest commit.
  • Once someone else has pushed to a Dependabot branch, Dependabot stops rebasing it automatically. Comment @dependabot recreate to start over (the lock file is refreshed again on the new PR).

changelog_check

Fails a pull request that doesn't add an entry under [Unreleased] in CHANGELOG.md, so release_prepare never finds that section empty. It checks that the PR adds non-blank lines to the changelog and that [Unreleased] has content (which also catches a malformed changelog). Skipped for PRs labelled skip-changelog, PRs opened by Dependabot, and release/v* PRs.

Use it when

  • Your repo keeps a Keep a Changelog CHANGELOG.md and releases with release_prepare, which fails if [Unreleased] is empty.
  • You want contributors to describe user-visible changes in the PR that makes them, not at release time.

Examples

Basic:

# .github/workflows/changelog.yml
name: Changelog
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]

jobs:
  changelog:
    uses: stajichlab/gh_workflows/.github/workflows/changelog_check.yml@v2

Different file and label, more bots skipped, and only for PRs into dev:

name: Changelog
on:
  pull_request:
    branches: [dev]
    types: [opened, synchronize, reopened, labeled, unlabeled]

jobs:
  changelog:
    uses: stajichlab/gh_workflows/.github/workflows/changelog_check.yml@v2
    with:
      changelog_path: docs/CHANGELOG.md
      skip_label: no-changelog
      skip_actors: "dependabot[bot] renovate[bot] pre-commit-ci[bot]"

Including labeled and unlabeled makes adding the skip label re-run the check. Create the skip label in each repo, and make the check required in branch protection if it should block merging.

Reference

Input Default Description
changelog_path CHANGELOG.md Changelog location
skip_label skip-changelog Label that skips the check
skip_actors dependabot[bot] Space-separated PR authors to skip

citation_check

Validates CITATION.cff against the Citation File Format schema with cffconvert, and warns (without failing) if its version differs from the latest v* tag on the base branch, or from the PR's version on a release/v* PR. Does nothing if the file doesn't exist, unless required: true.

Use it when

  • Your repo has a CITATION.cff (for GitHub's "Cite this repository" button or Zenodo archiving) and edits to it should be checked before they merge.
  • You want an early warning that the citation version has drifted from the released version.

release_prepare also validates the file at release time; this check catches problems in the PR that causes them.

Examples

Basic: check when the file changes.

# .github/workflows/citation.yml
name: Citation
on:
  pull_request:
    paths: [CITATION.cff]
  push:
    branches: [main]
    paths: [CITATION.cff]

jobs:
  citation:
    uses: stajichlab/gh_workflows/.github/workflows/citation_check.yml@v2

Require the file, for repos that must always be citable. It runs on every PR, so deleting the file is caught too:

name: Citation
on:
  pull_request:

jobs:
  citation:
    uses: stajichlab/gh_workflows/.github/workflows/citation_check.yml@v2
    with:
      required: true

Reference

Input Default Description
ref triggering commit Branch, tag or commit to check
citation_path CITATION.cff Citation file location
required false Fail if the file is missing

python_test

Runs a Python project's tests across a matrix. There is one workflow per installer:

Workflow Installs with Matrix input
python_test_pip.yml pip python_versions
python_test_conda.yml conda (micromamba) python_versions
python_test_pixi.yml pixi (--locked) environments

Call one per installer you support. All three share the same test steps, so they behave the same apart from the install. Each can put externally built tools from artifacts on PATH and upload coverage to Codecov.

Note

python_test.yml is the internal core the three wrappers call. It is not part of the public interface and its inputs may change in any release; call the wrappers instead.

Use it when

  • Your repo is a Python package and needs tests on several Python versions.
  • You support more than one way to install (pip, conda/bioconda, pixi) and want to test each without keeping separate CI files in step.
  • Tests need external command-line tools (aligners, tree builders) built or downloaded earlier in the run.

Examples

Simple pip package (installs -e .[dev], runs pytest on Python 3.10–3.14):

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    uses: stajichlab/gh_workflows/.github/workflows/python_test_pip.yml@v2

Linux and macOS, two Python versions, with a ruff lint job:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/ruff-action@v4

  test:
    uses: stajichlab/gh_workflows/.github/workflows/python_test_pip.yml@v2
    with:
      runs_on: '["ubuntu-latest", "macos-latest"]'
      python_versions: '["3.11", "3.13"]'

All three installers, external tools and coverage (Phyling's setup):

name: CI
on:
  push:
    branches: [main, dev]
  pull_request:

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

jobs:
  build-tools:   # repo-specific, uploads artifacts named tool-*
    uses: ./.github/workflows/build-tools.yml

  pip:
    needs: build-tools
    uses: stajichlab/gh_workflows/.github/workflows/python_test_pip.yml@v2
    with:
      tools_artifact_pattern: tool-*
      test_command: pytest --cov --cov-report=xml
    secrets:   # passing the token turns on the Codecov upload
      codecov_token: ${{ secrets.CODECOV_TOKEN }}

  conda:
    uses: stajichlab/gh_workflows/.github/workflows/python_test_conda.yml@v2
    with:
      environment_file: dev_environment.yml
      python_versions: '[""]'   # use the Python pinned in the file

  pixi:
    uses: stajichlab/gh_workflows/.github/workflows/python_test_pixi.yml@v2
    with:
      environments: '["dev"]'
      test_command: |
        command -v astral && command -v fasttree && command -v iqtree
        pytest

Several pixi environments (for example one per Python version, defined in pixi.toml), running a pixi task:

jobs:
  test:
    uses: stajichlab/gh_workflows/.github/workflows/python_test_pixi.yml@v2
    with:
      environments: '["py310", "py313"]'
      test_command: pixi run test

Reference

test_command runs as a bash script (set -euo pipefail) inside the installed environment (the pip Python, the conda environment, or the pixi environment), so it sees its packages and tools. Put any setup lines before the tests in the same script.

Inputs shared by all three:

Input Default Description
ref triggering commit Branch, tag or commit to test
runs_on ["ubuntu-latest"] JSON list of runner images
tools_artifact_pattern "" Artifacts from the calling run whose files go on PATH
test_command pytest Bash script that runs the tests (may span several lines)

Installer-specific inputs:

Workflow Input Default Description
pip python_versions ["3.10", …, "3.14"] JSON list of Python versions
pip pip_install -e .[dev] Arguments to pip install
conda python_versions ["3.10", …, "3.14"] JSON list of Python versions; [""] uses the file's Python
conda environment_file environment.yml File that installs the project and test dependencies
pixi environments ["default"] JSON list of pixi environments
Secret Description
codecov_token Codecov upload token. When passed, coverage.xml is uploaded, flagged by installer and target

bioconda_recipe_check

Checks that the conda recipe kept in your repo is identical to the one in bioconda-recipes. If they differ, the job fails and the diff is written to the job summary; it passes again once they match. No issue is opened: put the calling workflow's status badge in your README and it shows the state at a glance. It only reports: the maintainer opens the bioconda-recipes PR by hand.

The comparison is exact, line for line, so any difference is reported, including a version bump that bioconda's autobump PR has not merged yet.

Use it when

  • Your repo keeps a copy of its bioconda recipe, and you want to know when the two drift apart.

Examples

Weekly check:

# .github/workflows/bioconda-check.yml
name: Bioconda recipe check
on:
  schedule:
    - cron: "0 6 * * 1"   # Mondays
  workflow_dispatch:

jobs:
  check:
    uses: stajichlab/gh_workflows/.github/workflows/bioconda_recipe_check.yml@v2
    permissions:
      contents: read
    with:
      recipe_path: conda/meta.yaml
      bioconda_recipe_path: recipes/phyling/meta.yaml   # only if not recipes/<repo name>/meta.yaml

Badge for your README (the file name is the calling workflow's, not this one's):

[![Bioconda recipe](https://github.com/OWNER/REPO/actions/workflows/bioconda-check.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/bioconda-check.yml)

Add ?branch=main to the badge URL if the workflow also runs on other branches.

Reference

Input Default Description
recipe_path required Path to the recipe in your repo
bioconda_recipe_path recipes/<repo name, lowercased>/meta.yaml Path to the recipe in bioconda-recipes
ref triggering commit Branch, tag or commit to read the recipe from
Output Description
differs true if the recipes differ, false if they are identical

Needs only contents: read. When the recipes differ the job fails and the diff appears in the run's job summary.

bioconda_recipe_solve

Checks that a noarch Python conda recipe can actually be installed. It does a dry-run solve (nothing is downloaded) of the recipe's run requirements from conda-forge and bioconda, once per supported Python, with glibc pinned to bioconda's build image (2.17). The job fails if any Python cannot be solved, and the job summary lists the result per Python. This catches what bioconda's CI would reject: a dependency with no build for one of your Pythons, or one that needs a newer glibc.

It complements bioconda_recipe_check: that one reports drift from bioconda's copy, this one reports a recipe that cannot be installed.

Use it when

  • Your package is noarch Python on bioconda and you want to know before submitting that its dependencies resolve on every Python you claim to support.
  • As a gate before tagging a release.

Examples

On recipe or Python range changes, and before a release:

# .github/workflows/recipe-solve.yml
name: Recipe solve
on:
  push:
    branches: [main]
    paths: ["bioconda/meta.yaml", "pyproject.toml"]
  pull_request:
    paths: ["bioconda/meta.yaml", "pyproject.toml"]
  workflow_dispatch:
  workflow_call:   # so a publish workflow can call it before tagging

jobs:
  solve:
    uses: stajichlab/gh_workflows/.github/workflows/bioconda_recipe_solve.yml@v2
    permissions:
      contents: read
    with:
      recipe_path: bioconda/meta.yaml

Reference

Input Default Description
recipe_path bioconda/meta.yaml Path to the recipe in your repo
python_versions from the recipe Space-separated Pythons to solve for, e.g. "3.11 3.12"
glibc 2.17 glibc version to solve against (CONDA_OVERRIDE_GLIBC)
ref triggering commit Branch, tag or commit to read the recipe from
Output Description
failed Space-separated Pythons that could not be solved (empty if all solved)

Needs only contents: read.

Python versions. Unless python_versions is given, they are every minor version allowed by the `python

=3.X,<3.Yline underrun:, which may be written out (python >=3.10,<3.15) or use {% set %} variables (python >={{ python_min }},<{{ python_max }}`).

Limits. The recipe is read with simple text parsing, not rendered: only {% set x = "..." %} variables substituted into {{ x }} are understood, and selectors (# [py<311]) are dropped as comments. Only run requirements are solved, so it suits noarch Python recipes, not compiled ones. recipe.yaml (rattler-build) is not supported.

Versioning

Pin callers to a major tag (@v2). Within v2, inputs and outputs stay compatible; the v2 tag is moved to each new compatible release automatically. Breaking changes get v3. The v1 tag still works for existing callers but gets no new releases; see the 2.0.0 entry in CHANGELOG.md for what changed. Every release is listed in the changelog.

Releasing this repo

This repo releases itself with its own workflows (the repo-only callers below use ./.github/workflows/..., so they always run the current code):

  1. Add an entry under [Unreleased] in CHANGELOG.md with every PR. changelog.yml enforces this (label a PR skip-changelog if it needs none).
  2. Run Actions → Release (release.yml) with a bump type: patch for fixes, minor for new workflows or inputs, major for breaking changes. It opens a Release v<version> PR.
  3. Review and merge the PR. publish.yml then tags v<version> and creates the GitHub release (via release_publish), and a second job moves v<major> (e.g. v2) to it, so callers pinned to @v2 get the release. Prereleases, and a patch to an older minor version, leave v<major> where it is.

The first release is major from no tags, giving v1.0.0 and v1.

Development

  • release.yml, publish.yml and changelog.yml run this repo's own releases and changelog check (see Releasing this repo).
  • lint.yml runs actionlint on every push to main and every PR.
  • test_release_prepare.yml runs release_prepare end to end against a throwaway orphan branch with a v0.1.0 tag, checks the release branch and the draft PR, then deletes the PR, branches and tag. It runs on pushes to main that touch either workflow, or manually. It needs Allow GitHub Actions to create and approve pull requests enabled in this repo.
  • test_release_publish.yml publishes a test prerelease (v0.0.0-test.<run id>, never marked latest) from a throwaway orphan branch with an attached artifact, checks the tag, notes, asset and branch deletion, then deletes the release, tag and branches. The merged-PR trigger path is not covered.
  • test_sync_dev.yml runs sync_dev end to end on three throwaway branch pairs (already up to date, clean merge, conflict), checks the results and the conflict PR, then deletes the PR and branches. The "push rejected" fallback needs branch protection and is not covered. Same triggers and repo setting as above.
  • test_citation_check.yml runs citation_check on throwaway orphan branches with a valid CITATION.cff matching its tag (required: true) and with no file, both of which must pass, and checks that the pinned cffconvert rejects an invalid file. The invalid case calls cffconvert directly, since a failing reusable-workflow call would fail the whole test run.
  • test_python_test.yml builds a tiny package on a throwaway orphan branch (with a conda environment file and a freshly generated pixi.lock) and runs the python_test_pip, _conda and _pixi wrappers against it (pip with two Python versions and a fake tool from an artifact on PATH). The test commands check that they run inside the right environment and Python version.
  • test_bioconda_recipe_check.yml copies phyling's live bioconda recipe onto a throwaway orphan branch and checks that it is reported as identical. The different-recipe case is not run, since the failing job would fail the test.
  • test_bioconda_recipe_solve.yml commits two small fixed recipes, one with a literal python >=3.X,<3.Y and one using {% set python_min/python_max %}, to a throwaway orphan branch and checks that both solve (the second also with an explicit python_versions). The unsolvable case is not run, since the failing job would fail the test.
  • test_container_build.yml builds a tiny image from a throwaway orphan branch for a release and a prerelease version, runs the smoke test and checks the tags, then pushes, signs and verifies an unversioned test image and deletes it again.
  • test_container_cleanup.yml pushes and signs two images under one tag in a throwaway GHCR package, runs container_cleanup with min_age_days: 0 (first as a dry run), checks that the untagged image and its signature are gone while the tagged image, its child manifests and its signature remain, then deletes the package.
  • Dependabot updates the pinned action SHAs monthly.

About

A centralized repo for reusable GitHub workflows

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors