Cookbook

Practical recipes for common workflow patterns. Every snippet is valid code against the current ghagen API — copy, adapt, and run ghagen synth.

Matrix build across Python versions

Run the same job against multiple Python versions. In Python, dynamic matrix dimensions go in Matrix.extras; in TypeScript, they are top-level keys in the matrix_ object. include and exclude are typed fields in both.

Python

from ghagen import Job, Matrix, Step, Strategy

test = Job(
    name="Test (Python ${{ matrix.python-version }})",
    runs_on="ubuntu-latest",
    timeout_minutes=15,
    strategy=Strategy(
        matrix=Matrix(
            extras={"python-version": ["3.11", "3.12", "3.13"]},
        ),
    ),
    steps=[
        Step(uses="actions/checkout@v4"),
        Step(
            uses="actions/setup-python@v5",
            with_={"python-version": "${{ matrix.python-version }}"},
        ),
        Step(name="Install", run="pip install -e '.[dev]'"),
        Step(name="Test", run="pytest"),
    ],
)

TypeScript

import { job, step, strategy } from "@ghagen/ghagen";

const test = job({
  name: "Test (Python ${{ matrix.python-version }})",
  runsOn: "ubuntu-latest",
  timeoutMinutes: 15,
  strategy: strategy({
    matrix_: {
      "python-version": ["3.11", "3.12", "3.13"],
    },
  }),
  steps: [
    step({ uses: "actions/checkout@v4" }),
    step({
      uses: "actions/setup-python@v5",
      with_: { "python-version": "${{ matrix.python-version }}" },
    }),
    step({ name: "Install", run: "pip install -e '.[dev]'" }),
    step({ name: "Test", run: "pytest" }),
  ],
});

Matrix over multiple OSes

runs_on is typed as a string, so an expression needs Raw (Python) or raw() (TypeScript) to get through. exclude trims unwanted combinations.

Python

from ghagen import Job, Matrix, Raw, Step, Strategy

Job(
    name="Cross-platform test",
    runs_on=Raw("${{ matrix.os }}"),
    timeout_minutes=20,
    strategy=Strategy(
        matrix=Matrix(
            extras={
                "os": ["ubuntu-latest", "macos-latest", "windows-latest"],
                "python-version": ["3.11", "3.12", "3.13"],
            },
            exclude=[
                {"os": "windows-latest", "python-version": "3.11"},
            ],
        ),
    ),
    steps=[
        Step(uses="actions/checkout@v4"),
        Step(
            uses="actions/setup-python@v5",
            with_={"python-version": "${{ matrix.python-version }}"},
        ),
        Step(name="Test", run="pytest"),
    ],
)

TypeScript

import { job, step, raw, strategy } from "@ghagen/ghagen";

job({
  name: "Cross-platform test",
  runsOn: raw("${{ matrix.os }}"),
  timeoutMinutes: 20,
  strategy: strategy({
    matrix_: {
      os: ["ubuntu-latest", "macos-latest", "windows-latest"],
      "python-version": ["3.11", "3.12", "3.13"],
      exclude: [{ os: "windows-latest", "python-version": "3.11" }],
    },
  }),
  steps: [
    step({ uses: "actions/checkout@v4" }),
    step({
      uses: "actions/setup-python@v5",
      with_: { "python-version": "${{ matrix.python-version }}" },
    }),
    step({ name: "Test", run: "pytest" }),
  ],
});

Cache dependencies

Both languages use Step (Python) or step() (TypeScript) with the actions/cache action directly. restore-keys takes a newline-joined string of prefix keys.

Python

from ghagen import Step

steps = [
    Step(uses="actions/checkout@v4"),
    Step(uses="actions/setup-python@v5", with_={"python-version": "3.12"}),
    Step(
        name="Cache pip",
        uses="actions/cache@v4",
        with_={
            "key": "pip-${{ hashFiles('requirements.txt') }}",
            "path": "~/.cache/pip",
            "restore-keys": "pip-",
        },
    ),
    Step(name="Install", run="pip install -r requirements.txt"),
    Step(name="Test", run="pytest"),
]

TypeScript

import { step } from "@ghagen/ghagen";

const steps = [
  step({ uses: "actions/checkout@v4" }),
  step({ uses: "actions/setup-python@v5", with_: { "python-version": "3.12" } }),
  step({
    name: "Cache pip",
    uses: "actions/cache@v4",
    with_: {
      key: "pip-${{ hashFiles('requirements.txt') }}",
      path: "~/.cache/pip",
      "restore-keys": "pip-",
    },
  }),
  step({ name: "Install", run: "pip install -r requirements.txt" }),
  step({ name: "Test", run: "pytest" }),
];

Job dependencies with needs

A downstream job lists its upstream dependencies with needs (string or list of strings) and can read their outputs via needs.<job>.outputs.*.

Python

from ghagen import Job, Step

jobs = {
    "build": Job(
        runs_on="ubuntu-latest",
        timeout_minutes=10,
        outputs={"version": "${{ steps.ver.outputs.value }}"},
        steps=[
            Step(uses="actions/checkout@v4"),
            Step(
                id="ver",
                name="Compute version",
                run="echo 'value=1.2.3' >> $GITHUB_OUTPUT",
            ),
        ],
    ),
    "release": Job(
        runs_on="ubuntu-latest",
        needs="build",
        if_="github.ref == 'refs/heads/main'",
        timeout_minutes=10,
        steps=[
            Step(run="echo Releasing ${{ needs.build.outputs.version }}"),
        ],
    ),
}

TypeScript

import { job, step } from "@ghagen/ghagen";

const jobs = {
  build: job({
    runsOn: "ubuntu-latest",
    timeoutMinutes: 10,
    outputs: { version: "${{ steps.ver.outputs.value }}" },
    steps: [
      step({ uses: "actions/checkout@v4" }),
      step({
        id: "ver",
        name: "Compute version",
        run: "echo 'value=1.2.3' >> $GITHUB_OUTPUT",
      }),
    ],
  }),
  release: job({
    runsOn: "ubuntu-latest",
    needs: "build",
    if_: "github.ref == 'refs/heads/main'",
    timeoutMinutes: 10,
    steps: [step({ run: "echo Releasing ${{ needs.build.outputs.version }}" })],
  }),
};

Pass artifacts between jobs

Both languages use Step (Python) or step() (TypeScript) with the actions/upload-artifact action in the producer and actions/download-artifact in the consumer. needs ensures the producer finishes first.

Python

from ghagen import Job, Step

jobs = {
    "build": Job(
        runs_on="ubuntu-latest",
        timeout_minutes=15,
        steps=[
            Step(uses="actions/checkout@v4"),
            Step(name="Build wheel", run="python -m build"),
            Step(
                name="Upload artifact",
                uses="actions/upload-artifact@v4",
                with_={"name": "dist", "path": "dist/"},
            ),
        ],
    ),
    "publish": Job(
        runs_on="ubuntu-latest",
        needs="build",
        timeout_minutes=10,
        steps=[
            Step(
                name="Download artifact",
                uses="actions/download-artifact@v4",
                with_={"name": "dist", "path": "dist/"},
            ),
            Step(name="Publish", run="twine upload dist/*"),
        ],
    ),
}

TypeScript

import { job, step } from "@ghagen/ghagen";

const jobs = {
  build: job({
    runsOn: "ubuntu-latest",
    timeoutMinutes: 15,
    steps: [
      step({ uses: "actions/checkout@v4" }),
      step({ name: "Build wheel", run: "python -m build" }),
      step({
        name: "Upload artifact",
        uses: "actions/upload-artifact@v4",
        with_: { name: "dist", path: "dist/" },
      }),
    ],
  }),
  publish: job({
    runsOn: "ubuntu-latest",
    needs: "build",
    timeoutMinutes: 10,
    steps: [
      step({
        name: "Download artifact",
        uses: "actions/download-artifact@v4",
        with_: { name: "dist", path: "dist/" },
      }),
      step({ name: "Publish", run: "twine upload dist/*" }),
    ],
  }),
};

Use secrets and environment variables

In Python, expr.secrets["NAME"] renders as ${{ secrets.NAME }} — wrap it in str() when assigning to a typed dict[str, str] field like env. In TypeScript, use the secrets proxy object (e.g. secrets.GITHUB_TOKEN).

Prefer the typed accessors over hand-written "${{ secrets.FOO }}" strings — they keep typos in secret names out of your workflows and renames ripple through your code.

Python

from ghagen import Job, Step, expr

Job(
    name="Publish release notes",
    runs_on="ubuntu-latest",
    timeout_minutes=10,
    env={
        "GH_TOKEN": str(expr.secrets["GITHUB_TOKEN"]),
        "RELEASE_CHANNEL": "stable",
    },
    steps=[
        Step(uses="actions/checkout@v4"),
        Step(
            name="Comment on release",
            run="gh release edit ${{ github.ref_name }} --notes-file NOTES.md",
        ),
    ],
)

TypeScript

import { job, step, secrets } from "@ghagen/ghagen";

job({
  name: "Publish release notes",
  runsOn: "ubuntu-latest",
  timeoutMinutes: 10,
  env: {
    GH_TOKEN: secrets.GITHUB_TOKEN,
    RELEASE_CHANNEL: "stable",
  },
  steps: [
    step({ uses: "actions/checkout@v4" }),
    step({
      name: "Comment on release",
      run: "gh release edit ${{ github.ref_name }} --notes-file NOTES.md",
    }),
  ],
});

Scheduled (cron) workflows

Schedule entries go into the trigger’s schedule field as a list. You can combine them with a workflow dispatch trigger to allow manual runs too.

Python

from ghagen import (
    Job,
    On,
    ScheduleTrigger,
    Step,
    Workflow,
    WorkflowDispatchTrigger,
)

nightly = Workflow(
    name="Nightly Build",
    on=On(
        schedule=[ScheduleTrigger(cron="0 9 * * *")],
        workflow_dispatch=WorkflowDispatchTrigger(),
    ),
    jobs={
        "build": Job(
            runs_on="ubuntu-latest",
            timeout_minutes=30,
            steps=[
                Step(uses="actions/checkout@v4"),
                Step(name="Nightly build", run="make nightly"),
            ],
        ),
    },
)

TypeScript

import { workflow, job, step, on, scheduleTrigger, workflowDispatch } from "@ghagen/ghagen";

const nightly = workflow({
  name: "Nightly Build",
  on: on({
    schedule: [scheduleTrigger({ cron: "0 9 * * *" })],
    workflowDispatch: workflowDispatch({}),
  }),
  jobs: {
    build: job({
      runsOn: "ubuntu-latest",
      timeoutMinutes: 30,
      steps: [
        step({ uses: "actions/checkout@v4" }),
        step({ name: "Nightly build", run: "make nightly" }),
      ],
    }),
  },
});

Reusable workflows with workflow_call

Define a workflow that accepts workflow_call inputs and reference it from another workflow by passing uses on a job.

Callee (.github/workflows/deploy.yml)

Python

from ghagen import (
    Job,
    On,
    Permissions,
    Step,
    Workflow,
    WorkflowCallTrigger,
)
from ghagen.models.trigger import WorkflowCallInput

deploy = Workflow(
    name="Deploy",
    on=On(
        workflow_call=WorkflowCallTrigger(
            inputs={
                "environment": WorkflowCallInput(
                    description="Target environment",
                    required=True,
                    type="string",
                ),
            },
        ),
    ),
    permissions=Permissions(contents="read", id_token="write"),
    jobs={
        "deploy": Job(
            runs_on="ubuntu-latest",
            environment="${{ inputs.environment }}",
            timeout_minutes=15,
            steps=[
                Step(uses="actions/checkout@v4"),
                Step(name="Deploy", run="./deploy.sh"),
            ],
        ),
    },
)

TypeScript

import { workflow, job, step, on, permissions, workflowCall } from "@ghagen/ghagen";

const deploy = workflow({
  name: "Deploy",
  on: on({
    workflowCall: workflowCall({
      inputs: {
        environment: {
          description: "Target environment",
          required: true,
          type: "string",
        },
      },
    }),
  }),
  permissions: permissions({ contents: "read", idToken: "write" }),
  jobs: {
    deploy: job({
      runsOn: "ubuntu-latest",
      environment: "${{ inputs.environment }}",
      timeoutMinutes: 15,
      steps: [step({ uses: "actions/checkout@v4" }), step({ name: "Deploy", run: "./deploy.sh" })],
    }),
  },
});

Caller

A job that references the reusable workflow via uses. Such a job has no steps of its own and inherits its runner from the callee.

Python

from ghagen import Job, expr

release = Job(
    name="Deploy to production",
    uses="./.github/workflows/deploy.yml",
    with_={"environment": "production"},
    secrets={"DEPLOY_KEY": str(expr.secrets["DEPLOY_KEY"])},
)

TypeScript

import { job, secrets } from "@ghagen/ghagen";

const release = job({
  name: "Deploy to production",
  uses: "./.github/workflows/deploy.yml",
  with_: { environment: "production" },
  secrets: { DEPLOY_KEY: secrets.DEPLOY_KEY },
});

Multiline scripts

Both languages support writing inline multiline scripts with natural indentation.

In Python, write Step.run as a triple-quoted string with natural Python indentation; auto-dedent removes the common leading whitespace when the workflow is emitted (see below). In TypeScript, JavaScript template literals let you write the script without leading indentation in the first place, so there is nothing to dedent when authoring — but toYaml and toData still apply the same emit-time auto-dedent as Python, so a script that does carry leading indentation (e.g. built programmatically) is normalized the same way in both languages.

Python

from ghagen import Step

Step(
name="Build and test",
run="""
echo "Building..."
make build
echo "Testing..."
make test
""",
)

TypeScript

import { step } from "@ghagen/ghagen";

step({
  name: "Build and test",
  run: `echo "Building..."
make build
echo "Testing..."
make test`,
});

Relative indentation within the script is preserved:

Python

Step(
    name="Deploy if ready",
    run="""
        if [ "$READY" = "true" ]; then
            ./deploy.sh
        else
            echo "Not ready"
        fi
    """,
)

TypeScript

step({
  name: "Deploy if ready",
  run: `if [ "$READY" = "true" ]; then
    ./deploy.sh
else
    echo "Not ready"
fi`,
});

For shell line continuations, Python requires \\ (double backslash) since \ at end-of-line is a Python line continuation. TypeScript template literals also use \\ for a literal backslash:

Python

Step(
    name="Create PR",
    run="""
        gh pr create \\
          --title "My PR" \\
          --body "Automated PR"
    """,
)

TypeScript

step({
  name: "Create PR",
  run: `gh pr create \\
  --title "My PR" \\
  --body "Automated PR"`,
});

For github-script and other actions that take script content via with_ (a field the emitter never dedents — auto-dedent only ever touches a Step’s run), Python provides the dedent helper. In TypeScript, template literals handle this naturally:

Python

from ghagen import Step, dedent

Step(
    uses="actions/github-script@v7",
    with_={"script": dedent("""
const issue = await github.rest.issues.create({
owner: context.repo.owner,
repo: context.repo.repo,
title: 'Automated issue',
});
console.log(`Created #${issue.data.number}`);
""")},
)

TypeScript

import { step } from "@ghagen/ghagen";

step({
  uses: "actions/github-script@v7",
  with_: {
    script: `const issue = await github.rest.issues.create({
  owner: context.repo.owner,
  repo: context.repo.repo,
  title: 'Automated issue',
});
console.log(\`Created #\${issue.data.number}\`);`,
  },
});

Auto-dedent is enabled by default in both languages — to_yaml/toYaml and to_data/toData all dedent each Step’s run string unless you pass auto_dedent=False / autoDedent: false explicitly. To disable it project-wide instead, set auto_dedent = false in your config; this option is supported by both ports.

.ghagen.yml

options:
  auto_dedent: false

Conditional jobs and steps

if_ (safe alias for the reserved word if) works on both Job and Step in both languages.

Python

from ghagen import Job, Step

Job(
    name="Deploy",
    runs_on="ubuntu-latest",
    timeout_minutes=15,
    if_="github.event_name == 'push' && github.ref == 'refs/heads/main'",
    steps=[
        Step(uses="actions/checkout@v4"),
        Step(name="Build", run="make build"),
        Step(
            name="Smoke test (main only)",
            run="./smoke-test.sh",
            if_="github.ref == 'refs/heads/main'",
        ),
    ],
)

TypeScript

import { job, step } from "@ghagen/ghagen";

job({
  name: "Deploy",
  runsOn: "ubuntu-latest",
  timeoutMinutes: 15,
  if_: "github.event_name == 'push' && github.ref == 'refs/heads/main'",
  steps: [
    step({ uses: "actions/checkout@v4" }),
    step({ name: "Build", run: "make build" }),
    step({
      name: "Smoke test (main only)",
      run: "./smoke-test.sh",
      if_: "github.ref == 'refs/heads/main'",
    }),
  ],
});

Composite action alongside your workflows

You can emit composite actions as well as workflows. Use app.add_action() and the action is written to action.yml (or <dir>/action.yml) next to your repo root.

Python

from ghagen import (
    Action,
    App,
    ActionInput,
    Branding,
    CompositeRuns,
    Step,
)

check_action = Action(
name="My Check",
description="Run the project's canonical checks",
branding=Branding(icon="check-circle", color="green"),
inputs={
"config": ActionInput(
description="Path to config file",
required=False,
default="config.toml",
),
},
runs=CompositeRuns(
steps=[
Step(
name="Run checks",
run='mycheck --config "${{ inputs.config }}"',
shell="bash",
),
],
),
)

app = App()
app.add_action(check_action) # -> ./action.yml

TypeScript

import { App, action, actionInputDef, branding, compositeRuns, step } from "@ghagen/ghagen";

const checkAction = action({
  name: "My Check",
  description: "Run the project's canonical checks",
  branding: branding({ icon: "check-circle", color: "green" }),
  inputs: {
    config: actionInputDef({
      description: "Path to config file",
      required: false,
      default: "config.toml",
    }),
  },
  runs: compositeRuns({
    using: "composite",
    steps: [
      step({
        name: "Run checks",
        run: 'mycheck --config "${{ inputs.config }}"',
        shell: "bash",
      }),
    ],
  }),
});

const app = new App();
app.addAction(checkAction);
await app.synth();

Use this pattern when you want one file to be the source of truth for both your CI workflows and the composite action other repos consume.