CircleCI to GitHub Actions Blueprint

What and Why

CircleCI defines pipelines in .circleci/config.yml with orbs (reusable packages), executors, contexts, and workflows. Teams already on GitHub often consolidate CI/CD into GitHub Actions to keep code, pipelines, and identity in one platform, reduce a second vendor and its access to their repositories, and use native OpenID Connect (OIDC) for keyless cloud authentication. Both systems are YAML pipeline-as-code, so the core concepts map well, but the execution model, caching, and reuse mechanisms differ enough to require care.

The goal is feature parity with cleaner reuse: shared logic in reusable workflows and composite actions, secrets minimized through OIDC, and runners sized to the workload.

Phases

Assessment. Inventory CircleCI config: jobs, workflows, orbs, contexts (shared secrets), executors, caching, and test splitting. Identify orbs that need a GitHub Actions equivalent (a marketplace action or a custom composite/Docker action) and any CircleCI-specific features such as SSH reruns, test splitting by timing, or approval jobs. Record current pipeline duration and success rate as a baseline.

Design. Map CircleCI workflows to GitHub Actions workflows, jobs to jobs, and orbs to reusable workflows (workflow_call) or composite actions. Translate CircleCI contexts into GitHub Actions secrets and environments with required reviewers. Replace stored cloud keys with OIDC federation so jobs assume a cloud role for short-lived credentials instead of holding long-lived keys. Plan the runner strategy: GitHub-hosted runners for general work, self-hosted runners for special hardware, large builds, or private network access.

Pilot. Migrate one representative repository end to end. Recreate matrix builds with the matrix strategy, port caching to actions/cache with correct keys, and validate that environments and required reviewers gate deploys. Confirm OIDC cloud auth works end to end and measure pipeline duration against the baseline.

Migration. Convert repositories in waves. Extract shared logic into reusable workflows and composite actions stored in a central repo so teams do not duplicate YAML. Add branch protection requiring Actions status checks, and pin third-party actions by commit SHA for supply-chain safety. Keep CircleCI running until each repo reaches parity, comparing outputs.

Decommission. Once a repo's GitHub Actions pipeline is stable, remove the CircleCI config, disable the project, and revoke CircleCI's repository access and stored contexts/secrets.

Key Risks and Mitigations

• Pipeline logic drift. Orb behavior, executors, and test splitting may not translate exactly. Compare outputs during a parallel-run period, pin action versions by SHA, and write checks that assert key behaviors.
• Secret migration. Contexts hold credentials that are easy to miss. Move secrets to GitHub Actions secrets and environments, prefer OIDC over stored keys, and rotate everything during the move.
• Runner capacity. Heavy or specialized builds can overwhelm hosted runners and slow everyone down. Use self-hosted runner groups (for example via the Actions Runner Controller on Kubernetes) for those workloads and monitor queue times.

Recommended Tooling

GitHub Actions with reusable workflows and composite actions, actions/cache for caching, OIDC federation for cloud auth, self-hosted runners (Actions Runner Controller on Kubernetes) for special needs, an artifact registry, and the native code scanning/SAST workflows. Pin third-party actions by commit SHA.

Success Metrics

Track lead time for changes, deployment frequency, build success rate, and median pipeline duration before and after migration.

Prerequisites

Repositories on GitHub, a cloud account configured for OIDC trust, agreement on a runner strategy, and a parallel-run window for validating parity.