GitHub Actions to CircleCI Converter

Convert GitHub Actions workflows to CircleCI config.yml. Translates jobs, executors, matrix builds, caching (restore_cache/save_cache), workspaces, and the most-used Actions. Browser-only, no upload.

Migrating from GitHub Actions to CircleCI

GitHub Actions and CircleCI both centre on jobs that depend on other jobs and run inside a chosen executor. The two main translation tasks are mapping GitHub Actions to CircleCI orb commands or shell, and re-modelling caching from a single `actions/cache` action into CircleCI's explicit `restore_cache` + `save_cache` pair.

The converter emits CircleCI 2.1 config with explicit Docker executors, an auto-generated `workflows.main.jobs` graph that mirrors your GitHub `needs:` graph, and built-in steps (`checkout`, `save_cache`, `restore_cache`, `store_artifacts`) where they apply.

Syntax cheat sheet

ConceptGitHub ActionsCircleCI
Version key(none)version: 2.1
Workflow namename: CI(workflow names live under workflows.<name>:)
Executorruns-on: ubuntu-latestdocker: [{ image: cimg/base:stable }]
Checkout- uses: actions/checkout@v4- checkout
Cache- uses: actions/cache@v4 with: { key, path }- restore_cache: { keys: [<key>] } - save_cache: { key, paths: [<path>] }
Artifact- uses: actions/upload-artifact@v4- store_artifacts: { path: <p> } - persist_to_workspace: { root, paths }
Matrixstrategy: matrix: node: [18, 20]workflows: main: jobs: - test: matrix: parameters: node: [18, 20]
Variable${{ matrix.node }}<< matrix.node >>

Gotchas to watch for

  • warning

    Caches are explicit pairs

    CircleCI requires you to call `restore_cache` before the work and `save_cache` after. The converter generates both; do not delete either half.

  • warning

    Workspaces vs artifacts

    `actions/upload-artifact` becomes both `store_artifacts` (visible in the UI) and `persist_to_workspace` (consumable by downstream jobs). Drop whichever you don't need.

  • warning

    Conditional jobs use filters

    GitHub `if:` at job level becomes a CircleCI workflow `filters:` block on the job entry. Step-level `if:` is not supported in CircleCI — those become bash conditionals inside the run script.

  • warning

    Schedules belong in workflows

    GitHub `on: schedule:` is translated into a `workflows.main.triggers.schedule:` block. Schedules cannot live on individual jobs in CircleCI 2.1.

  • warning

    Manual approvals are workflow nodes

    A manual gate becomes a `type: approval` job in the workflow, not a step. The converter creates one when it sees `environment.required-reviewers` or equivalent.

Worked examples

Node.js test → CircleCI

Single job with cimg executor, native checkout, and an explicit cache pair.

GitHub Actions
name: CI
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test
CircleCI
version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - restore_cache:
          keys: [npm-{{ checksum "package-lock.json" }}]
      - run: npm ci
      - save_cache:
          key: npm-{{ checksum "package-lock.json" }}
          paths: [node_modules]
      - run: npm test
workflows:
  main:
    jobs: [test]

Frequently asked questions

Does it use orbs automatically?expand_more

Yes — common GitHub Actions like setup-node and aws-actions/configure-aws-credentials map to the corresponding CircleCI orbs (`circleci/node`, `circleci/aws-cli`). For unmapped actions, the converter emits shell commands that achieve the same outcome.

What about `actions/setup-node@v4`?expand_more

The converter emits a `cimg/node:<version>` Docker image plus an `npm ci` step. If you need a specific Node version per matrix combo, switch to a CircleCI matrix at the workflow level.

How are timeouts handled?expand_more

GitHub `timeout-minutes:` becomes the CircleCI executor's `no_output_timeout:` setting on the run step. Job-level timeouts are not first-class in CircleCI 2.1.

Are GitHub composite actions supported?expand_more

Composite actions are flagged for review. CircleCI's equivalent is a custom command (under `commands:` at the top of config.yml). The converter does not currently auto-generate command definitions.

Related Tools

data_object

YAML Formatter

Format and validate YAML. Convert YAML to JSON or JSON to YAML. Supports 2 and 4 space indentation.

timer

Cron Builder

Visual builder for cron-job schedules.

filter_list_off

Gitignore Generator

Generate .gitignore files for any language, framework, or IDE — 100+ templates, 100% client-side.

schema

JSON Schema Generator

Generate a JSON Schema from one or more sample JSONs — drafts 2020-12, 2019-09, 7, 6, 4. Detects formats (date-time, email, uuid, ipv4, uri), extracts $defs, validates with AJV, and exports to YAML, TypeScript, and Zod. 100% in your browser.

auto_awesome

AI Coding Rules

Curated rules-file library and generator for Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, Aider, Continue, and Cody. Browse 20 hand-crafted .cursorrules / CLAUDE.md / copilot-instructions.md files for popular stacks, build a custom one with the wizard, or convert any rules file between AI-tool formats.