# Chains & steps (/pipeline-sdk/reference/chains) {/* Generated by docs-site/scripts/generate-dsl-docs.ts — do not edit. */} ## `group` [#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. ```python 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** ```python >>> import harmont as hm >>> proj = hm.rust.project() >>> leaves = hm.group([proj.test(), proj.clippy(), proj.fmt()]) ``` ## `scratch` [#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. ```python scratch() -> Step ``` **Returns** `Step` — A new root `Step` with no command or parent. **Examples** ```python >>> import harmont as hm >>> step = hm.scratch().sh("echo hello") ``` ## `sh` [#sh] Start a chain with a single shell command. Shorthand for `scratch().sh(cmd, ...)`. All keyword arguments are forwarded to `Step.sh`. ```python 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** ```python >>> import harmont as hm >>> step = hm.sh("cargo build") ``` ## `Step` [#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 [#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()` [#stepfork] ```python 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()` [#stepsh] ```python 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` [#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. ```python 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** ```python >>> import harmont as hm >>> @hm.target() ... def apt_base() -> hm.Step: ... return hm.sh("apt-get update") ``` ## `wait` [#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. ```python 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** ```python >>> import harmont as hm >>> p = hm.pipeline(hm.sh("make build"), hm.wait(), hm.sh("make deploy")) ```