Reusable GitHub Actions workflows for stajichlab repositories.
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.
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.
- You want releases to go through a reviewed pull request instead of tagging by hand.
- The version should come from git tags, with
CHANGELOG.mdandCITATION.cffkept in step automatically. - Each repo stores its version somewhere different (
pyproject.toml,__init__.py, an RDESCRIPTIONfile, ...) 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.
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$" DESCRIPTIONPatch 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.xRelease 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.
| 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.
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.
- You use
release_prepareand 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.
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: writeFull 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: writeRequire 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: releaseRe-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| 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.
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.
- Your repo develops on
dev(ordevelop) and releases frommain, anddevshould pick up the release commit (version bump, changelog) right after each release. - Fixes made on
mainduring a release must not be lost ondev. devis protected, so updates must arrive as a pull request.
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: writeDifferent 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-userOn 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| 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.
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 |
- 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
Dockerfileshould 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.
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: --helpTest 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: --helpBuild 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: --versionMulti-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: trueOnly 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| 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.
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 OCIsubjectfield 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.
latestor 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.
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: writeSeveral 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| 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.
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.
- Your repo uses pixi with a committed
pixi.lock, and Dependabot updates dependencies inpyproject.tomlorpixi.toml. - CI installs with
--locked(aspython_test_pixialways does), so Dependabot PRs fail until the lock file is regenerated.
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 writeManifest 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| 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_TOKENdoes not trigger workflows, so the PR's CI does not rerun on the lock-file commit. If CI checks are required for merging, passtoken, 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 recreateto start over (the lock file is refreshed again on the new PR).
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.
- Your repo keeps a Keep a Changelog
CHANGELOG.mdand releases withrelease_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.
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@v2Different 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.
| 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 |
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.
- 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.
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@v2Require 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| 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 |
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.
- 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.
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@v2Linux 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
pytestSeveral 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 testtest_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 |
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.
- Your repo keeps a copy of its bioconda recipe, and you want to know when the two drift apart.
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.yamlBadge for your README (the file name is the calling workflow's, not this one's):
[](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.
| 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.
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.
- 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.
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| 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.Y
line 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.
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.
This repo releases itself with its own workflows (the repo-only callers below use ./.github/workflows/..., so
they always run the current code):
- Add an entry under
[Unreleased]in CHANGELOG.md with every PR.changelog.ymlenforces this (label a PRskip-changelogif it needs none). - Run Actions → Release (
release.yml) with a bump type:patchfor fixes,minorfor new workflows or inputs,majorfor breaking changes. It opens aRelease v<version>PR. - Review and merge the PR.
publish.ymlthen tagsv<version>and creates the GitHub release (viarelease_publish), and a second job movesv<major>(e.g.v2) to it, so callers pinned to@v2get the release. Prereleases, and a patch to an older minor version, leavev<major>where it is.
The first release is major from no tags, giving v1.0.0 and v1.
release.yml,publish.ymlandchangelog.ymlrun this repo's own releases and changelog check (see Releasing this repo).lint.ymlruns actionlint on every push tomainand every PR.test_release_prepare.ymlrunsrelease_prepareend to end against a throwaway orphan branch with av0.1.0tag, checks the release branch and the draft PR, then deletes the PR, branches and tag. It runs on pushes tomainthat touch either workflow, or manually. It needs Allow GitHub Actions to create and approve pull requests enabled in this repo.test_release_publish.ymlpublishes 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.ymlrunssync_devend 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.ymlrunscitation_checkon throwaway orphan branches with a validCITATION.cffmatching 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.ymlbuilds a tiny package on a throwaway orphan branch (with a conda environment file and a freshly generatedpixi.lock) and runs thepython_test_pip,_condaand_pixiwrappers against it (pip with two Python versions and a fake tool from an artifact onPATH). The test commands check that they run inside the right environment and Python version.test_bioconda_recipe_check.ymlcopies 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.ymlcommits two small fixed recipes, one with a literalpython >=3.X,<3.Yand one using{% set python_min/python_max %}, to a throwaway orphan branch and checks that both solve (the second also with an explicitpython_versions). The unsolvable case is not run, since the failing job would fail the test.test_container_build.ymlbuilds 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.ymlpushes and signs two images under one tag in a throwaway GHCR package, runscontainer_cleanupwithmin_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.