CircleCI to GitHub Actions Converter

Migrating from CircleCI to GitHub Actions

Syntax cheat sheet

Gotchas to watch for

• warning

  Workflow definition disappears

  CircleCI puts the DAG in a workflows section at the bottom; GitHub puts it in `needs:` on each job. The converter inverts the structure.

• warning

  Cache keys with checksums

  CircleCI cache keys often use `{{ checksum "..." }}` — these translate to `${{ hashFiles('...') }}` in GitHub Actions. The converter rewrites the syntax.

• warning

  Pipeline parameters

  CircleCI pipeline parameters (`<< pipeline.parameters.foo >>`) become GitHub Actions inputs. They only fire on `workflow_dispatch` triggers.

• warning

  Approval jobs

  A `type: approval` job becomes a GitHub Actions job that waits for a deployment-environment approval. The converter emits a stub and a TODO.

• warning

  Resource classes

  CircleCI resource classes (`resource_class: large`) have no direct equivalent — choose `runs-on:` from the GitHub-hosted matrix (e.g. `ubuntu-latest-4-cores`) or use self-hosted runners.

Worked examples

version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm ci
      - run: npm test
workflows:
  build:
    jobs: [test]

name: CI
on:
  push: {}
jobs:
  test:
    runs-on: ubuntu-latest
    container: cimg/node:20.10
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

Frequently asked questions