Pipelines

Pipelines live in the repository at .slipway/*.yaml (one pipeline per file) or slipway.yaml at the root. The format is YAML 1.2. A JSON Schema is published at slipway.systems/schema/pipeline-v1.json, and slipway validate checks files against it and runs semantic validation.

The design goals: readable at a glance, no surprises for people coming from GitHub Actions or GitLab CI, deploys are first-class (a job can bind to an environment), and everything dynamic is CEL inside ${{ }}.

Anatomy

version: 1                      # required; integer
name: api-service               # required; unique per project
description: Build, test and ship the API
on:                             # triggers
  push: { branches: [main, "release/**"] }
  pull_request:
  schedule:
    - cron: "0 3 * * 1-5"
  manual:
    inputs:
      version: { type: string, required: true, description: Semver to release }
      dry_run: { type: boolean, default: false }
env:                            # pipeline-wide environment
  GOFLAGS: -mod=readonly
defaults:
  runs_on: [linux, x64]
  timeout: 30m
  shell: bash
concurrency:
  group: ${{ pipeline.name }}-${{ git.ref }}
  cancel_in_progress: true
permissions:                    # scopes of the job OIDC token
  id_token: write
  contents: read
stages: [...]                   # or jobs: [...] for a single implicit stage

A pipeline has either stages: (explicit) or jobs: (shorthand: one implicit stage), not both. It may alternatively extends: an org-level base pipeline.

Map

Topic	Page
When pipelines start	Triggers
DAG, matrix, retries, concurrency, deploy jobs	Stages and jobs
run, uses, template, outputs	Steps
Services, caches, artifacts, test reports	Caches, artifacts and services
Reusable steps, org templates, extends	Templates and reusable steps
Checking a file	Validation and editor support
Every key	Reference (generated from the schema)
Expressions	Expressions and functions

A complete example

version: 1
name: web
on:
  push: { branches: [main] }
  pull_request:
jobs:
  - name: test
    runs_on: [linux]
    container: { image: node:22 }
    steps:
      - uses: slipway/checkout@v1
      - run: npm ci && npm test
  - name: deploy
    needs: [test]
    if: ${{ git.branch == "main" }}
    environment: { name: production, service: web }
    steps:
      - uses: slipway/deploy@v1
        with: { strategy: canary }