Migrate from CircleCI to GitHub Actions: Step-by-Step

Moving from CircleCI to GitHub Actions is mostly a translation job: .circleci/config.yml become workflows and jobs. This guide maps the concepts and walks the steps.

CircleCI and GitHub Actions share the same building blocks - pipelines, jobs, and steps - under different names. The migration is methodical: translate the config, port secrets and caching, and verify in parallel before cutting over.

Concept mapping

Migration steps

1. Inventory your CircleCI pipelines and list every job, trigger, and secret.
2. Create .github/workflows/ci.yml and translate one pipeline at a time.
3. Move secrets into GitHub Actions encrypted secrets (port contexts and orbs).
4. Add actions/cache for dependencies to match prior build speed.
5. Run the new workflow in parallel with the old pipeline on a branch and compare results.
6. Cut over once green, then archive the old config.

Common pitfalls

• Orbs map to Actions - swap each orb for a marketplace action.
• Workflows/requires become needs.
• Executors/Docker images become runs-on and container jobs.

After you migrate: cut cost and flakiness

Once on GitHub Actions, the next wins are cost and reliability. Managed runners like Latchkey run the same workflows at roughly 69% lower per-minute cost, and self-healing retries transient failures automatically - so the pipeline you just migrated stays green and cheap.

Key takeaways

• .circleci/config.yml map cleanly to GitHub Actions workflows.
• Port secrets and caching to match speed and security.
• Run both pipelines in parallel before cutting over.
• Then move to managed runners to cut cost and flaky re-runs.

Frequently asked questions

Related guides