A Python-native CI/CD framework for defining, testing, and transpiling pipelines to GitHub Actions.
You can install pygha via pip:
pip install pyghaYou can install pygha from the psidhu22 channel:
conda install -c psidhu22 pyghaBelow is an example of a Python-defined pipeline that mirrors what most teams use in production —
build, lint, test, coverage, and deploy — all orchestrated through pygha.
from pygha import job, default_pipeline
from pygha.steps import shell, checkout, uses
# Configure the default pipeline to run on main push and PRs
default_pipeline(on_push=["main"], on_pull_request=True)
@job(
name="test",
matrix={"python": ["3.11", "3.12", "3.13"]},
)
def test_matrix():
"""Run tests across multiple Python versions."""
checkout()
# Use the matrix variable in your step arguments
uses(
"actions/setup-python@v5",
with_args={"python-version": "${{ matrix.python }}"}
)
shell("pip install .[dev]")
shell("pytest")
@job(name="deploy", depends_on=["test"])
def deploy():
"""Build and publish if tests pass."""
checkout()
uses("actions/setup-python@v5", with_args={"python-version": "3.11"})
shell("pip install build twine")
shell("python -m build")
shell("twine check dist/*")Once you have defined your pipelines (by default, pygha looks for files matching pipeline_*.py or *_pipeline.py in a .pipe directory), use the CLI to generate the GitHub Actions YAML files.
# Default behavior: Scans .pipe/ and outputs to .github/workflows/
pygha build-
--src-dir: Source directory containing your Python pipeline definitions (default: .pipe). -
--out-dir: Output directory where the generated YAML files will be saved (default: .github/workflows). -
--clean: Automatically deletes YAML files in the output directory that are no longer registered in your pipelines. This is useful when you rename or remove pipelines.If you have a manually created workflow file in your output directory that you want to preserve (e.g.,
manual-deploy.yml), add# pygha: keepto the first 10 lines of that file. The CLI will skip deleting it.
pygha allows you to write conditional workflows using Python syntax instead of raw YAML strings.
Use the @run_if decorator to skip entire jobs based on context.
from pygha.decorators import run_if
from pygha.expr import github
@job(name="nightly-scan")
@run_if(github.event_name == "schedule")
def security_scan():
"""Only runs on scheduled events."""
...Use the when context manager to group steps that should only run under certain conditions. Nested conditions are automatically AND-ed together.
from pygha.steps import when
from pygha.expr import runner, always, failure
@job
def conditional_steps():
# Simple check
with when(runner.os == 'Linux'):
shell("sudo apt-get update")
# Status check helper (runs even if previous steps failed)
with when(always()):
shell("echo 'Cleanup...'")
# Nested check: (failure()) AND (runner.os == 'Linux')
with when(failure()):
with when(runner.os == 'Linux'):
shell("echo 'Linux build failed!'")