Skip to content
Slipwaydocs

Migrate from GitHub Actions

Slipway’s syntax is deliberately familiar to Actions users. Most workflows convert by renaming keys.

Concept map

Section titled “Concept map”
GitHub Actions Slipway Notes
.github/workflows/*.yml .slipway/*.yaml One pipeline per file
name name
on: push / pull_request / schedule / workflow_dispatch on: push / pull_request / schedule / manual workflow_dispatch is manual with typed inputs
on: workflow_run on: pipeline Fan-in
on: repository_dispatch on: api or webhook
jobs.<id> (map) jobs: (list of name:) Jobs are a list with unique names
runs-on runs_on A list of labels; all must match
needs needs
if if CEL instead of the Actions expression language
strategy.matrix matrix include, exclude, fail_fast, max_parallel
container, services container, services Same idea; health: replaces options: --health-cmd
steps[].uses uses github://actions/checkout@v4 via the shim, or slipway/checkout@v1
steps[].run run
steps[].with with
steps[].env env
working-directory working_directory snake_case keys
continue-on-error continue_on_error
timeout-minutes timeout: 30m Duration strings
concurrency concurrency group, cancel_in_progress
permissions permissions id_token: write for OIDC
environment: production environment: { name: production, service: api } Backed by real environments
Environment protection rules Environment protection rules Richer: windows, freezes, policies
secrets.X secrets.X Only in env, with, services.env
vars.X vars.X
github.ref_name, github.sha git.branch, git.sha See contexts
$GITHUB_OUTPUT $SLIPWAY_OUTPUT Same key=value format
$GITHUB_ENV, $GITHUB_PATH $SLIPWAY_ENV, $SLIPWAY_PATH
::add-mask:: ::mask:: ::group::, ::error:: are the same
actions/cache cache: Keyed with restore_keys
actions/upload-artifact artifacts: or slipway/artifact-upload@v1
needs.<job>.outputs.x needs.<job>.outputs.x
hashFiles() hashFiles()
success(), failure(), always(), cancelled() same
Reusable workflows template: / extends: Versioned and immutable
Self-hosted runner labels Runner pool labels Free and unlimited

Worked conversion

Section titled “Worked conversion”

GitHub Actions:

name: ci
on:
  push: { branches: [main] }
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix: { node: [20, 22] }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "${{ matrix.node }}", cache: npm }
      - run: npm ci && npm test
  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    permissions: { id-token: write, contents: read }
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with: { role-to-assume: arn:aws:iam::123456789012:role/deploy, aws-region: eu-west-1 }
      - run: ./deploy.sh

Slipway:

version: 1
name: ci
on:
  push: { branches: [main] }
  pull_request:
jobs:
  - name: test
    runs_on: [linux]
    container: { image: "node:${{ matrix.node }}" }
    matrix: { node: ["20", "22"] }
    cache:
      - key: npm-${{ hashFiles("package-lock.json") }}
        paths: [~/.npm]
    steps:
      - uses: slipway/checkout@v1
      - run: npm ci && npm test


  - name: deploy
    needs: [test]
    if: git.branch == "main"
    runs_on: [linux]
    environment: { name: production, service: web }
    permissions: { id_token: write }
    steps:
      - uses: slipway/checkout@v1
      - run: ./deploy.sh      # OIDC to AWS: see /docs/secrets/oidc-aws
      - uses: slipway/deploy@v1   # or let the strategy engine do the rollout
        with: { strategy: canary }

What changed beyond renaming:

  • The deploy job is now a deployment of a release into a production environment with approvals and a strategy. Define those in the app.
  • No setup-node: the job runs in a node container. Use images instead of setup actions.
  • AWS access uses OIDC federation directly or the AWS integration.

Migration order

Section titled “Migration order”
  1. Add a Slipway pipeline next to the workflow for your test job; compare.
  2. Replace marketplace actions: language setup becomes container.image, caches become cache:, artifacts become artifacts:, cloud login becomes OIDC.
  3. Move secrets: re-create repository and environment secrets in Slipway (write-only), or switch to external references.
  4. Create environments and protection rules to replace GitHub environment rules and required reviewers.
  5. Disable the workflow when Slipway has run green for a while.