Your first pipeline and deployment

This tutorial extends the hello-world pipeline into a real delivery flow: build, release, deploy to staging automatically, then to production after an approval. It assumes you have a project, a connected repository and a runner (see the quickstarts).

1. Model what you deploy

A service is the deployable unit. An environment is where it runs. Create them in the UI (Deployments, Services, Environments) or with the API.

• Service api, kind container, artifact source: your registry repository.
• Environments staging and production, in that order. On production, require 1 approval from the deployer role.
• An infrastructure on each environment: for example a Kubernetes cluster and namespace. See Kubernetes.

2. Write the pipeline

.slipway/api.yaml

version: 1
name: api
on:
  push: { branches: [main] }
  pull_request:
defaults:
  runs_on: [linux]
jobs:
  - name: test
    container: { image: golang:1.27 }
    cache:
      - key: go-${{ hashFiles("go.sum") }}
        restore_keys: [go-]
        paths: [~/go/pkg/mod]
    steps:
      - uses: slipway/checkout@v1
      - run: go test ./...

  - name: build
    needs: [test]
    if: ${{ git.branch == "main" }}
    outputs:
      version: ${{ steps.ver.outputs.version }}
    steps:
      - uses: slipway/checkout@v1
      - id: ver
        run: echo "version=1.4.${{ git.short_sha }}" >> "$SLIPWAY_OUTPUT"
      - uses: slipway/docker-build@v1
        with: { push: true }
      - uses: slipway/release-create@v1

  - name: deploy-staging
    needs: [build]
    environment: { name: staging, service: api }
    steps:
      - uses: slipway/deploy@v1
        with:
          release: ${{ needs.build.outputs.version }}
          strategy: rolling

  - name: deploy-production
    needs: [deploy-staging]
    environment: { name: production, service: api }
    steps:
      - uses: slipway/deploy@v1
        with:
          release: ${{ needs.build.outputs.version }}
          strategy: canary

Key points:

• A job with environment: is a deploy job. It waits for that environment’s protection rules before starting, and its run is recorded as a deployment of a release.
• slipway/release-create@v1 freezes the artifact versions, variables and provenance into an immutable release.
• slipway/deploy@v1 delegates to the deploy engine, which runs the strategy (rolling, blue/green, canary) and shows progress in the pipeline.

Validate and push:

slipway validate
git add .slipway/api.yaml && git commit -m "Add api pipeline" && git push

3. Watch the deployment

slipway run list --pipeline api
slipway deployment list --status waiting_approval

When production is waiting for approval, an approver can decide in the UI, from a Slack message, or from the CLI:

slipway approve dep_01H... --comment "Checked the dashboards"

4. Promote and roll back later

Pipelines are one way to deploy. You can also create releases and let lifecycles drive promotion, Octopus style:

slipway release create api 1.4.0 --artifact image=ghcr.io/acme/api@sha256:abc...
slipway deploy api 1.4.0 --env staging --wait
slipway promote api --from staging --to production
slipway rollback api --env production

Where next

• Deployment strategies and canary verification
• Approvals and gates
• Lifecycles and channels