Pipeline YAML Schema

Top-level fields

Field	Type	Required	Description
name	string	yes	Pipeline name — used as the run command
description	string	no	Short description shown by pipe list
dot_file	string	no	Path to a .env file to load variables from (see Variables)
vars	map[string]string	no	User-defined variables (see Variables)
steps	[]Step	yes	Ordered list of steps

Step fields

Field	Type	Required	Default	Description
id	string	yes	—	Unique step identifier
run	string | []string | []SubRun	yes	—	Command(s) to execute (see run modes)
depends_on	string | []string	no	[]	Step ID(s) that must complete first
sensitive	bool	no	false	Exclude output from state files; always re-execute on resume
retry	int	no	0	Number of retries on failure
cache	bool | CacheConfig	no	false	Cache successful results (see Caching)
interactive	bool	no	false	Attach stdin/stdout/stderr to the terminal (see below)

SubRun fields

Used inside a run list when each item is a mapping:

Field	Type	Required	Default	Description
id	string	yes	—	Sub-run identifier (combined with step ID for env var: PIPE_<STEP>_<SUBRUN>)
run	string	yes	—	Command to execute
sensitive	bool	no	false	Exclude this sub-run’s output from state files

CacheConfig fields

Used when cache is a mapping instead of true:

Field	Type	Required	Description
expireAfter	string	yes	Expiry duration or wall-clock time

Expiry formats

Format	Example	Description
Go duration	30s, 10m, 1h, 24h	Relative duration from cache time
Wall-clock time	18:10 UTC, 15:00	Re-run after this time of day

DependsOn forms

The depends_on field accepts two YAML forms:

# Scalar — single dependency
depends_on: "build"

# Sequence — multiple dependencies
depends_on:
  - "lint"
  - "test"

Run forms

The run field accepts three YAML forms:

# Scalar — single command (output captured as PIPE_<STEP_ID>)
run: "echo hello"

# Sequence of strings — parallel commands (output NOT captured)
run:
  - "go vet ./..."
  - "golangci-lint run"

# Sequence of mappings — parallel named sub-runs (output captured per sub-run)
run:
  - id: linux
    run: "GOOS=linux go build -o dist/linux ."
  - id: darwin
    run: "GOOS=darwin go build -o dist/darwin ."

Interactive steps

Setting interactive: true on a step connects stdin, stdout, and stderr directly to the terminal instead of capturing output. This is useful for steps that start a user-facing session such as SSH, a REPL, or a shell.

Constraints:

• At most one interactive step per pipeline.
• Must use a single run command (not parallel strings or sub-runs).
• Must be a leaf node — no other step can depend on it.
• cache, output, retry, and sensitive are ignored on interactive steps.

The interactive step is excluded from the parallel DAG dispatch. After all non-interactive steps complete successfully, the compact UI is torn down and the interactive step runs synchronously with the terminal attached. If prior steps fail, the interactive step is skipped (and can be resumed later).

Stdin must be a TTY — piping into a pipeline that has an interactive step will fail with a clear error.

steps:
  - id: push-key
    run: "aws ec2-instance-connect send-ssh-public-key ..."
  - id: connect
    run: "ssh ec2-user@$PIPE_VAR_HOST"
    depends_on: push-key
    interactive: true

Full example

name: release
description: "Build and release the project"
vars:
  registry: "ghcr.io/myorg"
steps:
  - id: get-version
    run: "git describe --tags --abbrev=0"

  - id: checks
    run:
      - "go vet ./..."
      - "go test -race ./..."

  - id: build
    run:
      - id: linux
        run: "GOOS=linux go build -ldflags '-X main.version=$PIPE_GET_VERSION' -o dist/linux ."
      - id: darwin
        run: "GOOS=darwin go build -ldflags '-X main.version=$PIPE_GET_VERSION' -o dist/darwin ."
    depends_on: "checks"

  - id: push
    run: "docker push $PIPE_VAR_REGISTRY/app:$PIPE_GET_VERSION"
    depends_on: "build"
    retry: 2