Core concepts

The handful of objects you need to understand to be productive with Poyesis.

Poyesis is built around a small set of objects. Learn these five and the rest of the product follows naturally.

Projects#

A project is the top-level container for a product or service. It groups repositories, pipelines, environments, and the people who work on them. Most teams map one project to one deployable service.

Pipelines#

A pipeline is a declarative description of how your code goes from commit to production. Pipelines are defined as code in a poyesis.yaml file at the root of your repository.

Stages#

A pipeline is composed of stages. Each stage runs a command in an isolated container. Stages without a needs: field run in parallel; needs: creates ordering.

poyesis.yaml

pipeline:
  - stage: lint
    run: npm run lint
  - stage: build
    run: npm run build
  - stage: deploy
    needs: [lint, build]   # waits for both
    run: poyesis deploy --env production

Environments#

An environment is a named deploy target — staging, production, a preview, or your own custom target. Environments carry their own secrets and protection rules.

Environment	Auto-deploy	Approvals	Secrets scope
`preview`	Yes	None	Preview
`staging`	Yes	None	Staging
`production`	Manual gate	Required	Production

Runs#

Every execution of a pipeline is a run. A run records its commit, the result of each stage, logs, artifacts, and which environment it deployed to.

Runs are immutable. Re-running a pipeline creates a new run that links back to the original — so your deploy history is always a complete, auditable record.

How they fit together#

A project owns repositories

Connect one or more repos to a project.

A repository defines a pipeline

The poyesis.yaml describes its stages.

A pipeline deploys to environments

Each deploy stage targets an environment with its own rules.

Each push produces a run

Fully recorded and auditable.