Migrar de CircleCI a GitHub Actions: paso a paso
Última actualización
Migrar de CircleCI a GitHub Actions es, en su mayor parte, una tarea de traducción: los jobs siguen siendo jobs, los workflows se convierten en needs, los orbs pasan a ser actions del marketplace y save_cache se convierte en actions/cache. Un pipeline pequeño se migra en una tarde. Las partes más complicadas son los secrets, los contexts y todo lo que dependía de funciones específicas de CircleCI, como resource_class o la división de tests. Esta guía cubre la equivalencia entre ambos, una traducción real, el Importer automatizado y un plan de cambio que evita tiempos de inactividad.
Para la comparación a nivel de producto, consulte CircleCI vs GitHub Actions y alternativas a CircleCI.
Equivalencia de conceptos
| CircleCI | GitHub Actions |
|---|---|
.circleci/config.yml | .github/workflows/*.yml (un archivo por workflow) |
workflows: con requires | jobs.<id>.needs |
jobs: | jobs: |
Executor docker: / machine: | runs-on: más container: si quiere una imagen para el job |
Imágenes docker: secundarias | services: |
resource_class | Etiqueta del runner, por ejemplo un runner más grande o una etiqueta de self-hosted |
steps: - run | steps: - run |
checkout | actions/checkout |
save_cache / restore_cache | actions/cache, o cache: en las actions setup-* |
persist_to_workspace / attach_workspace | actions/upload-artifact / actions/download-artifact |
store_artifacts | actions/upload-artifact |
store_test_results | Una action de informes de tests, o upload-artifact de los archivos JUnit |
parallelism: N + división de tests | strategy.matrix; consulte sharding de tests |
| Orbs | Actions del marketplace, composite actions y reusable workflows |
| Contexts | Environments, secrets y variables de organización |
| Variables de entorno del proyecto | Secrets y variables del repositorio |
filters: branches | on.push.branches / condiciones if: |
Workflows programados (triggers: schedule) | on.schedule; consulte programaciones cron |
when: / unless: | Expresiones if: |
Un pipeline realista, en paralelo
CircleCI: una aplicación Node con Postgres, build y test, y después deploy desde main:
# .circleci/config.yml
version: 2.1
orbs:
node: circleci/node@5
jobs:
test:
docker:
- image: cimg/node:22.11
- image: cimg/postgres:16.4
environment:
POSTGRES_PASSWORD: postgres
resource_class: large
parallelism: 4
steps:
- checkout
- restore_cache:
keys:
- npm-v1-{{ checksum "package-lock.json" }}
- npm-v1-
- run: npm ci
- save_cache:
key: npm-v1-{{ checksum "package-lock.json" }}
paths: [~/.npm]
- run:
command: |
TESTS=$(circleci tests glob "test/**/*.test.js" | circleci tests split --split-by=timings)
npm test -- $TESTS
environment:
DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
- store_test_results:
path: reports
deploy:
docker:
- image: cimg/node:22.11
steps:
- checkout
- run: ./scripts/deploy.sh
workflows:
ci:
jobs:
- test
- deploy:
requires: [test]
context: production
filters:
branches:
only: main
Equivalente en GitHub Actions:
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest # or [self-hosted, Linux, compiler-ci]
strategy:
fail-fast: false
matrix:
shard: [1, 2, 3, 4]
services:
postgres:
image: postgres:16.4
env:
POSTGRES_PASSWORD: postgres
ports: ["5432:5432"]
options: >-
--health-cmd "pg_isready -U postgres"
--health-interval 5s --health-retries 10
env:
DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx jest --shard=${{ matrix.shard }}/4 --ci --reporters=default --reporters=jest-junit
- uses: actions/upload-artifact@v4
if: always()
with:
name: test-results-${{ matrix.shard }}
path: reports
deploy:
needs: test
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v6
- run: ./scripts/deploy.sh
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
Qué cambia y por qué:
- La imagen Docker principal se convierte en el propio runner. Use
setup-nodeen lugar decimg/node, o mantenga una imagen concontainer:. - Las imágenes secundarias se convierten en
services:. El servicio es accesible enlocalhostmediante el mapeo de puertos cuando el job se ejecuta directamente en el runner, y por nombre de servicio cuando el propio job usacontainer:. Añada un health check para que los tests no arranquen antes de que Postgres esté listo. parallelism: 4junto concircleci tests splitse convierte en una matrix. CircleCI divide según tiempos registrados; el--shardde Jest divide según el orden de los archivos y no tiene en cuenta los tiempos. Si el equilibrio de tiempos le importa, consulte sharding de tests.- El context
productionse convierte en unenvironment: production, que además puede requerir aprobaciones y acotar los secrets.
Secrets y variables de entorno
Las variables de proyecto de CircleCI se convierten en secrets del repositorio. Los contexts compartidos entre proyectos se convierten en secrets de organización (restringidos por repositorio) o en secrets de environment. No se pueden leer los valores de los secrets desde la interfaz de CircleCI, así que expórtelos desde el lugar donde los guardó originalmente; planifique esto con antelación. Los valores no sensibles van en variables de repositorio u organización, a los que se hace referencia como ${{ vars.NAME }}.
Para el acceso a la nube, prefiera credenciales de corta duración frente a claves almacenadas; consulte OIDC de GitHub Actions con AWS y cómo proteger GitHub Actions. Por defecto, los secrets no se pasan a los workflows activados desde forks.
Caché y artefactos
restore_cache con una lista de claves se corresponde directamente con key más restore-keys. La mayoría de las configuraciones se simplifican a cache: en setup-node, setup-python, setup-go y similares. Consulte las guías por ecosistema: npm, pip, Gradle, Go, y la guía general de caché. El límite de caché por repositorio es de 10 GB; consulte límites de caché.
Para persist_to_workspace, suba los archivos en un job y descárguelos en el siguiente:
- uses: actions/upload-artifact@v4
with: { name: build, path: dist }
# in the next job
- uses: actions/download-artifact@v4
with: { name: build }
Los artefactos se almacenan por ejecución, con un período de retención que puede configurar.
Conversión automatizada: GitHub Actions Importer
GitHub ofrece un Importer como extensión de gh que admite CircleCI, Jenkins, GitLab CI, Azure DevOps, Bamboo, Bitbucket Pipelines y Travis CI (según la documentación de GitHub, consultada en octubre de 2026). Necesita Docker y la CLI de GitHub.
gh extension install github/gh-actions-importer
gh actions-importer configure # sets up tokens for GitHub and CircleCI
gh actions-importer audit circle-ci --output-dir audit
gh actions-importer dry-run circle-ci --output-dir out ...
Los comandos documentados son audit (analiza sus pipelines), forecast (estima el uso de Actions a partir de ejecuciones anteriores), dry-run (escribe localmente los workflows convertidos) y migrate (abre un pull request). Ejecute audit primero: le indica qué construcciones se convierten y cuáles requieren trabajo manual, lo que hace realista el plan del proyecto. Trate la salida como un primer borrador. Los orbs y los comandos personalizados suelen requerir conversión manual, y el YAML convertido es extenso. Consulte la documentación actual del Importer para conocer los flags exactos de su versión.
Plan de transición
- Audite con el Importer y liste los orbs, contexts y pipelines programados.
- Porte un workflow (normalmente el job principal de pruebas) y ejecútelo en una rama.
- Ejecute ambos en paralelo durante una o dos semanas. Compare la duración y la tasa de aprobación; corrija las diferencias inestables.
- Traslade los secretos y los entornos, y después los jobs de despliegue. Pruebe primero los despliegues contra un entorno de staging.
- Actualice la protección de ramas para exigir los checks de GitHub en lugar de los de CircleCI.
- Desactive los disparadores de CircleCI, conserve la configuración en el historial de git y elimínela después de un ciclo de publicación.
Tras la migración: coste y velocidad
Los runners alojados por GitHub por defecto tienen 2 vCPU. Si sus jobs de CircleCI usaban las clases de recursos large o xlarge, es probable que los runners por defecto de GitHub le parezcan más lentos. Compare los runners más grandes de GitHub con las alternativas en precios de GitHub Actions. compiler.dev ejecuta el mismo workflow en máquinas de 8 vCPU / 16 GB por $0.008 por minuto cambiando runs-on a [self-hosted, Linux, compiler-ci], con un fallback automático a sus runners originales si algo falla; consulte precios.
Preguntas frecuentes
¿Cuánto tiempo lleva migrar de CircleCI a GitHub Actions?
Un único pipeline con orbs estándar: horas. Una docena de pipelines con orbs personalizados, contexts y lógica de despliegue: semanas, principalmente para validación y secretos.
¿Qué reemplaza a los orbs de CircleCI?
Actions del Marketplace para herramientas habituales, composite actions para secuencias de pasos reutilizables y reusable workflows para jobs completos.
¿Puedo mantener el reparto de pruebas por tiempos de CircleCI?
No de forma nativa. Jest y Playwright dividen por archivo o número de pruebas; para un equilibrado basado en tiempos, use un script de reparto o una herramienta diseñada para ello.
¿Pierdo la depuración por SSH de CircleCI?
No existe un equivalente integrado. Las actions de la comunidad abren una sesión SSH o tmate temporal; evalúe su seguridad antes de usarlas.
¿Puedo ejecutar ambos durante un tiempo?
Sí, y se recomienda. Ejecute ambos hasta que los resultados coincidan y después cambie los checks requeridos.
Relacionado
- Migrar de GitLab CI a GitHub Actions: paso a pasoMigre de GitLab CI a GitHub Actions con tabla de equivalencias de .gitlab-ci.yml, variables, caché, services, Importer y transición.
- Migrar de Jenkins a GitHub Actions: paso a pasoMigre de Jenkins a GitHub Actions con una tabla de equivalencias de Jenkinsfile, traducción lado a lado, credenciales, caché, agentes y plan de transición.
- CircleCI vs GitHub Actions con runners de compiler.devCircleCI frente a GitHub Actions en runners de compiler.dev: precios por créditos, diferencias de configuración y una guía de migración con YAML real.
- Mejores alternativas a CircleCI en 2026Las mejores alternativas a CircleCI: GitHub Actions, GitLab CI, Buildkite, Semaphore, Jenkins y compiler.dev, comparadas por precio, esfuerzo y encaje.