Chains & steps

`group`

Collect a list of steps into a tuple for use as a target return value.

pipeline() and @pipeline both accept a tuple of leaves. group() converts a list to that tuple for convenience.

group(steps) -> tuple[Step, ...]

Parameter	Type	Default	Description
`steps`	`list[Step] \| tuple[Step, ...]`	required	The leaf steps to collect.

Returns tuple[Step, ...] — A tuple of the input steps.

Examples

>>> import harmont as hm
>>> proj = hm.rust.project()
>>> leaves = hm.group([proj.test(), proj.clippy(), proj.fmt()])

`scratch`

Create a new root step with no command.

Use as the starting point for a chain, or call sh() at the module level to combine scratch() and .sh() in one call.

scratch() -> Step

Returns Step — A new root Step with no command or parent.

Examples

>>> import harmont as hm
>>> step = hm.scratch().sh("echo hello")

`sh`

Start a chain with a single shell command.

Shorthand for scratch().sh(cmd, ...). All keyword arguments are forwarded to Step.sh.

sh(cmd, *, cwd=None, label=None, cache=None, env=None, timeout_seconds=None, image=None, key=None) -> Step

Parameter	Type	Default	Description
`cmd`	`str`	required	Shell command to run.
`cwd`	`str \| None`	`None`	Directory to run in, relative to the workspace root. Omit to
run in the root.
`label`	`str \| None`	`None`	Human-facing label shown in the UI. Defaults to the command.
`cache`	`CachePolicy \| None`	`None`	Cache policy controlling result reuse across builds.
`env`	`dict[str, str] \| None`	`None`	Per-step environment variables merged on top of pipeline-level env.
`timeout_seconds`	`int \| None`	`None`	Hard wall-clock timeout in seconds.
`image`	`str \| None`	`None`	Local-mode Docker base image override for this step.
`key`	`str \| None`	`None`	Manual key override for this step in the v0 IR.

Returns Step — A new root Step with the command set.

Examples

>>> import harmont as hm
>>> step = hm.sh("cargo build")

`Step`

Immutable chain node — the primitive the pipeline SDK is built on.

Steps are constructed via scratch() or wait() and extended by calling .sh() or .fork() on the result. Every mutating method returns a new Step; the receiver is unchanged.

Fields

Field	Type	Default
`cmd`	`str \| None`	`None`
`parent`	`Step \| None`	`None`
`is_wait`	`bool`	`False`
`continue_on_failure`	`bool`	`False`
`label`	`str \| None`	`None`
`cache`	`CachePolicy \| None`	`None`
`env`	`dict[str, str] \| None`	`None`
`timeout_seconds`	`int \| None`	`None`
`image`	`str \| None`	`None`
`runner`	`str \| None`	`None`
`runner_args`	`dict[str, Any] \| None`	`None`
`key_override`	`str \| None`	`None`

`Step.fork()`

fork(label=None) -> Step

Create a branch point from this step.

Returns a new scratch-rooted Step whose parent is self. Downstream .sh() calls on the fork produce independent leaves that all share self as their nearest emitted ancestor.

Parameter	Type	Default	Description
`label`	`str \| None`	`None`	Optional label for the fork node in the UI.

Returns Step — A new Step branching from this one.

`Step.sh()`

sh(cmd, *, cwd=None, label=None, cache=None, env=None, timeout_seconds=None, image=None, runner=None, runner_args=None, key=None) -> Step

Append a shell command to this chain.

Returns a new Step; the receiver is unchanged (steps are immutable).

Parameter	Type	Default	Description
`cmd`	`str`	required	Shell command to run.
`cwd`	`str \| None`	`None`	Directory to run in, relative to the workspace root. Omit to
run in the root; pass a non-empty path to change directory first.
`label`	`str \| None`	`None`	Human-facing label shown in the UI. Defaults to the command.
`cache`	`CachePolicy \| None`	`None`	Cache policy controlling result reuse across builds.
`env`	`dict[str, str] \| None`	`None`	Per-step environment variables, merged on top of pipeline-level
env at render time.
`timeout_seconds`	`int \| None`	`None`	Hard wall-clock timeout for the step. The executor
kills the process after this many seconds.
`image`	`str \| None`	`None`	Local-mode Docker base image for this step. Ignored when the
step has a `builds_in` parent (the parent's snapshot wins).
`runner`	`str \| None`	`None`	Executor plugin runner name. `None` selects the default
Docker runner.
`runner_args`	`dict[str, Any] \| None`	`None`	Plugin-specific arguments validated by the runner's
schema.
`key`	`str \| None`	`None`	Manual key override for this step in the v0 IR. Auto-derived
from the command when omitted.

Returns Step — A new Step with this command appended to the chain.

`target`

Mark a function as a reusable, memoized pipeline building block.

The wrapped function may declare dependencies as parameters; each parameter name is resolved against the global target registry (pytest-fixture style). The return value is memoized per render so targets calling other targets dedup correctly.

target(*, name=None) -> Callable[[Callable[..., Any]], Callable[[], Any]]

Parameter	Type	Default	Description
`name`	`str \| None`	`None`	Registry key for this target. Defaults to the decorated
function's name. Override when the name collides with another
target or a more human-readable key is preferred.

Returns Callable[[Callable[..., Any]], Callable[[], Any]] — A decorator that registers and memoizes the wrapped function.

Examples

>>> import harmont as hm
>>> @hm.target()
... def apt_base() -> hm.Step:
...     return hm.sh("apt-get update")

`wait`

Insert a synchronization barrier between pipeline stages.

All steps emitted before the barrier must finish before any step emitted after it starts. Equivalent to Buildkite's wait step.

wait(*, continue_on_failure=False) -> Step

Parameter	Type	Default	Description
`continue_on_failure`	`bool`	`False`	When `True`, the barrier passes even if
upstream steps have failed, allowing cleanup or notification
steps to run.

Returns Step — A Step that lowers to a wait barrier in the v0 IR.

Examples

>>> import harmont as hm
>>> p = hm.pipeline(hm.sh("make build"), hm.wait(), hm.sh("make deploy"))

On this page