Getting started

Pipemesh runs your repository's pipelines and workflows from one file, pipemesh.yaml. Every change on your default branch becomes a revision you can follow from the first build to production.

Pipemesh works with GitHub today. GitLab and self-hosted repositories are coming soon.

The fastest way: let your coding agent do it

The Pipemesh skill teaches your coding agent to set up a repository. It reads the CI you already have, asks you about anything the code doesn't make clear, writes pipemesh.yaml, checks it, and offers you a pull request.

1. Add the skill

In Claude Code:

/plugin marketplace add pipemesh/skills
/plugin install pipemesh@pipemesh

In Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode or any agent that reads Agent Skills:

npx skills add pipemesh/skills

2. Ask for it

From your repository, ask your agent:

"Set up Pipemesh for this repo."

It works through it with you:

  • Reads your GitHub Actions, GitLab CI, Makefiles, deploy scripts, Dockerfiles, and Nx, Turborepo or Bazel setup.
  • Asks when the shape isn't clear, such as which jobs deploy, where, and in what order.
  • Writes pipemesh.yaml, and .pipemesh/*.yaml files when it grows.
  • Checks it with npx pipemesh check, and shows you the board it will draw with npx pipemesh preview.
  • Offers a pull request, with what's left for you to do before merging.

3. Turn it on

Sign in, connect your GitHub account or organization, and enable the repository. The skill walks you through it, or run:

npx pipemesh login     # sign in with GitHub
npx pipemesh connect   # install the Pipemesh GitHub App
npx pipemesh enable    # turn on the repository you're in

Merge the pull request and watch your first revision appear.

The skill tells you when a newer version is out. In Claude Code, run /plugin marketplace update pipemesh, or turn on auto-update under /plugin → Marketplaces. With npx skills, run npx skills update.

Organizations

Everything in Pipemesh belongs to an organization: your personal account is one, and so is each GitHub organization you connect.

  • Signing in is the whole sign-up. Your GitHub account becomes your personal organization.
  • Connecting installs the Pipemesh GitHub App on your account or on a GitHub organization you administer. The repositories you grant it show up in Pipemesh, and the ones you add or remove later follow on their own.
  • Members join on their own. Anyone in the GitHub organization is a member from their first sign-in, and its admins are owners. To add someone who isn't in it, use My account.
  • What you can do follows your GitHub role on each repository:
GitHub role In Pipemesh
admin, maintain operate its pipelines: approve, retry, cancel, enable
write see it under Your repositories, run its manual workflows
read follow everything

Organization owners can do everything. The App asks for as little as it can, and reads with short-lived tokens, so you never hand Pipemesh a personal token. GitHub integration lists its permissions.

Enable repositories

Open Repositories and enable the ones you want, one by one or several at once. From a checkout, npx pipemesh enable does the same, and npx pipemesh repos lists what's enabled.

A repository without pipemesh.yaml waits, and starts the moment the file lands on its default branch.

Write it by hand

pipemesh.yaml sits at the repository root and names everything the repository runs:

deployment:
  type: pipeline
  stages:
    - build
    - staging
  jobs:
    build:
      job_type: workflow
      stage: build
      body: !include .pipemesh/build.yaml
    deploy_staging:
      job_type: deploy
      production: false
      stage: staging
      needs:
        - build
      checkout:
        - deploy
      script: ./deploy/run.sh staging

pipemesh:
  pipelines:
    pipeline: !ref deployment
  workflows:
    checks:
      body: !include .pipemesh/ci.yaml
      on: pull_request
    nightly:
      body: !include .pipemesh/nightly.yaml
      on: schedule
      cron: "0 3 * * *"
  • pipemesh: is the only key Pipemesh reads. Every other root key is yours, reached with !ref.
  • pipelines: is the long-lived mainline: each commit on the default branch becomes a revision that moves through the stages.
  • workflows: are one-off runs, each on its trigger: a pull request, a schedule, a tag, a push, or nothing (you run it from its page).
  • job_type: says what a job is (build, deploy, workflow, …). It decides what the job checks out and when it can skip. A deploy runs only when what it reads changed.

The definition has the full grammar, Release flow how revisions move, and Why Pipemesh when to use a pipeline or a workflow.

Check it before you commit

npx pipemesh check

check loads your definition exactly as your repository will. It sends pipemesh.yaml and only the files it names, stores nothing, and prints any error with the file and the fix, then what each job checks out and when it skips.

npx pipemesh preview

preview opens the board your definition would draw, and what changes against the repository's current pipeline. The link works for anyone for 7 days. Add --watch and the page follows every save.

Install the CLI with npm install -g pipemesh to type pipemesh instead of npx pipemesh. It needs Node 20 or newer and tells you once a day when a newer version is out (PIPEMESH_NO_UPDATE_CHECK=1 turns that off). pipemesh version shows yours and the latest.

Watch it run

The catalog lists every enabled repository with its pipelines, workflows and their latest state. A pipeline's page is a live board: each revision moving through the jobs, logs as they stream, and buttons to approve, retry or cancel. Pull requests get their results as GitHub checks.

Pages follow your repository's path. /github.com/acme is an organization, /github.com/acme/shop a repository, and /github.com/acme/shop/-/checks one workflow: the /-/ is where the repository ends.

The same from your terminal:

npx pipemesh status                 # each job's state, and what each deploy has deployed
npx pipemesh watch                  # follow the latest revision until it settles
npx pipemesh logs deploy_staging    # a job's log
npx pipemesh deployed '#42'         # did pull request 42 reach production?

npx pipemesh help lists everything, and every command takes --json.

Something wrong?

Use Report a problem, in the account menu, on any error and in a job's panel. It sends what you write, plus what the page saw: recent API calls (no bodies or credentials), errors, versions and a screenshot. You can leave any of it out. From the terminal: npx pipemesh report "<what happened>". Reports go to the Pipemesh team and are deleted after 90 days.