pipeline-compose

Cross-repo CI orchestration that stays inside GitHub Actions.

needs: works great inside one repo. When your release spans a service repo, a QA repo, and an infra repo, you're back to repository_dispatch, PAT gymnastics, and tab-hopping across Actions runs with no shared context.

Pipeline Compose gives you one pipeline.yml: ordered stages, wait-for-completion, and context.* wiring across repos — without Jenkins, without custom polling scripts, without leaving Actions.

Stable release: v1.17.0 — pipeline-compose local, standalone run: executor, pipeline state store. Cross-repo GitHub App auth since v1.6.

You don't need a second CI platform. You need one pipeline graph that Actions can actually execute.

# .github/pipelines/pipeline.yml
version: 2
pipelines:
  release:
    stages:
      - id: ci
        workflow: .github/workflows/ci.yml

      - id: e2e
        workflow: .github/workflows/e2e.yml
        repo: my-org/qa-repo
        needs: [ci]
        inputs:
          image_tag: ${{ context.ci.image_tag }}

      - id: deploy
        workflow: .github/workflows/deploy.yml
        needs: [e2e]

flowchart TD
  ci["ci"]
  e2e["e2e<br/>my-org/qa-repo"]
  deploy["deploy"]
  ci --> e2e
  e2e --> deploy

pipeline-compose-run dispatches each stage, polls until done, downloads pipeline-compose-<stage> artifacts, and builds context for the next stage. One workflow run. One result.

• Synchronous — unlike raw dispatch, the orchestrator waits and fails the pipeline if a stage fails.
• Context merge — stage workflows export JSON via pipeline-compose-export; downstream stages read context.<stage>.<key>.
• Declarative — graph, when:, needs:, and cross-repo repo: live in YAML, not shell.

No generated workflow to commit unless you choose pipeline-compose-compile.

Each action README includes a self-contained glossary.

1. Pipeline file — pnpm run init scans workflows and writes starter v2 YAML (.github/pipelines/pipeline.yml):

version: 2
companion_workflows:
  - .github/workflows/release.yml
pipelines:
  release:
    stages:
      - id: ci
        workflow: .github/workflows/ci.yml
      - id: deploy
        workflow: .github/workflows/deploy.yml
        needs: [ci]

2. Export in any stage workflow that declares outputs::

- uses: aeswibon/pipeline-compose-export@v1.17.0
  if: success()
  with:
    stage_id: ci
    outputs: '{"image_tag":"${{ steps.build.outputs.tag }}"}'

3. Entry workflow (e.g. tag push):

- uses: aeswibon/pipeline-compose-run@v1.17.0
  with:
    pipeline_file: .github/pipelines/pipeline.yml

Cross-repo? Add repo: org/repo on the stage and configure a GitHub App (github_app_id + github_app_private_key) or repo_tokens_json on the run action.

Copy-paste examples: examples/ · Tutorial: docs/tutorials/tag-release-pipeline.md

PRs that touch pipeline YAML can get a mermaid + simulate + issues comment (see .github/workflows/pipeline-pr-comment.yml in this repo).

flowchart TD
  py["pipeline.yml"]
  run["pipeline-compose-run"]
  sw["Stage workflows"]
  ex["export artifacts<br/>outputs.json"]
  ctx["context merged"]
  inp["next stage inputs"]

  py --> run
  run --> sw
  sw --> ex
  ex --> ctx
  ctx --> inp
  inp --> run

Good fit: poly-repo release trains, platform-owned stage catalogs, validate-before-merge DAGs.

Probably not: single-repo linear CI (native needs: is enough), or full deployment-platform features (Spinnaker, Argo CD, etc.).

pnpm run init          # scan workflows → starter pipeline.yml; infers outputs + context_schema from export steps
pnpm run import turbo  # turbo.json → .github/pipelines/imported.yml (or import nx / import rush)
pnpm run validate .github/pipelines/pipeline.yml --repo-root . --workflows --strict --mermaid
pnpm run compile .github/pipelines/pipeline.yml -o .github/workflows/pipeline-generated.yml

See docs/development.md for the full command list and release process.

pnpm run act:full    # tests, validate, compile parity, bundles
pnpm run act:ci      # unit tests + build

Requires Docker and act. See .github/act/README.md.

MIT