Pipelines

Caching, build matrices, manual approvals, and reusable templates.

Pipelines are the core of Poyesis. This guide covers the features you'll reach for once your build → test → deploy basics are in place.

Caching#

Cache dependencies and build output between runs to cut minutes. Declare paths with a cache: key; the cache is keyed by a hash of the listed files.

poyesis.yaml
pipeline:
  - stage: build
    cache:
      key: deps-{{ hashFiles('package-lock.json') }}
      paths:
        - node_modules
        - .next/cache
    run: npm ci && npm run build

A good cache key changes only when it has to. Hash your lockfile, not your whole source tree — otherwise every commit misses the cache.

Build matrices#

Run the same stage across multiple versions or platforms in parallel with matrix:.

poyesis.yaml
pipeline:
  - stage: test
    matrix:
      node: ["20", "22", "24"]
    run: |
      nvm use ${{ matrix.node }}
      npm test

This expands into three parallel stages — one per Node version.

Manual approvals#

Gate sensitive stages behind a human approval. The pipeline pauses until an authorized teammate approves the run.

poyesis.yaml
pipeline:
  - stage: deploy
    environment: production
    approval:
      required: true
      reviewers: ["@platform-team"]
    run: poyesis deploy --env production

Approvals are enforced server-side. A reviewer listed in reviewers cannot approve their own run unless allowSelfApproval: true is set on the environment.

Reusable templates#

Extract common steps into a template and reference it across repositories with uses:.

Common questions#