Workflow

The Workflow class is the top-level model that maps to a complete GitHub Actions workflow YAML file. It contains the workflow name, triggers, permissions, environment variables, defaults, concurrency settings, and jobs.

Workflow

from ghagen import Workflow, On, Job, Step
from ghagen.models.trigger import PushTrigger

workflow = Workflow(
    name="CI",
    on=On(push=PushTrigger(branches=["main"])),
    jobs={
        "test": Job(
            runs_on="ubuntu-latest",
            steps=[Step(uses="actions/checkout@v4")],
        ),
    },
)
print(workflow.to_yaml())

Parameters

Parameter	Type	Default	Description
`name`	`str \| None`	`None`	The display name of the workflow.
`run_name`	`str \| None`	`None`	Custom name for workflow runs. Supports GitHub Actions expressions. Serialized as `run-name`.
`on`	`On \| dict \| None`	`None`	Trigger configuration for the workflow. See Triggers.
`permissions`	`Permissions \| Literal["read-all", "write-all"] \| Raw[str] \| None`	`None`	Token permissions. Can be a `Permissions` object or a string shorthand. See Permissions.
`env`	`dict[str, str] \| None`	`None`	Environment variables available to all jobs in the workflow.
`defaults`	`Defaults \| None`	`None`	Default settings for all `run` steps. See Defaults.
`concurrency`	`str \| Concurrency \| None`	`None`	Concurrency group configuration. Can be a string (group name) or a `Concurrency` object.
`jobs`	`dict[str, Job]`	`{}`	Map of job IDs to job definitions. See Job.

All models also accept these inherited parameters from the base class:

Parameter	Type	Default	Description
`extras`	`dict[str, Any]`	`{}`	Arbitrary key/value pairs merged into YAML output for fields not covered by the typed API.
`post_process`	`Callable \| None`	`None`	Callback to modify the YAML mapping before emission. See Escape Hatches.
`comment`	`str \| None`	`None`	Block comment emitted above this node in the YAML output.
`eol_comment`	`str \| None`	`None`	End-of-line comment for this node.

Per-field comments are attached by wrapping individual field values with with_comment() or with_eol_comment(). See Comments.

Methods

`to_yaml(header=DEFAULT) -> str`

Generate the complete YAML string for this workflow.

Argument	Type	Default	Description
`header`	`str \| None \| Callable[[HeaderVariables], str] \| _Sentinel`	`DEFAULT`	Header comment for the generated file. Omit to emit ghagen’s default header. Pass `None` to skip the header. Pass a `str` to emit it verbatim (no `{variable}` substitution; literal braces are preserved). Pass a callable to receive a fully-populated `HeaderVariables` dict and emit the returned string.

Returns the complete YAML string.

`to_yaml_file(path, header=DEFAULT) -> None`

Write the workflow YAML to a file. Creates parent directories if they don’t exist.

Argument	Type	Default	Description
`path`	`str \| Path`	required	File path to write to.
`header`	`str \| None \| Callable[[HeaderVariables], str] \| _Sentinel`	`DEFAULT`	Header comment. See `to_yaml()` for the four accepted shapes.

Defaults

Default settings for all run steps in a job or workflow.

Parameters

Parameter	Type	Default	Description
`run`	`DefaultsRun \| None`	`None`	Default run step settings.

DefaultsRun

Default shell and working directory for run steps.

Parameters

Parameter	Type	Default	Description
`shell`	`str \| Raw[str] \| None`	`None`	Default shell for run steps (e.g., `"bash"`, `"pwsh"`).
`working_directory`	`str \| None`	`None`	Default working directory. Serialized as `working-directory`.

Concurrency

Concurrency configuration for workflows or jobs. Prevents concurrent runs in the same group.

Parameters

Parameter	Type	Default	Description
`group`	`str`	required	Concurrency group name. Supports expressions.
`cancel_in_progress`	`bool \| None`	`None`	Whether to cancel in-progress runs when a new run is queued. Serialized as `cancel-in-progress`.