Saltar al contenido

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

CircleCIGitHub Actions
.circleci/config.yml.github/workflows/*.yml (un archivo por workflow)
workflows: con requiresjobs.<id>.needs
jobs:jobs:
Executor docker: / machine:runs-on: más container: si quiere una imagen para el job
Imágenes docker: secundariasservices:
resource_classEtiqueta del runner, por ejemplo un runner más grande o una etiqueta de self-hosted
steps: - runsteps: - run
checkoutactions/checkout
save_cache / restore_cacheactions/cache, o cache: en las actions setup-*
persist_to_workspace / attach_workspaceactions/upload-artifact / actions/download-artifact
store_artifactsactions/upload-artifact
store_test_resultsUna action de informes de tests, o upload-artifact de los archivos JUnit
parallelism: N + división de testsstrategy.matrix; consulte sharding de tests
OrbsActions del marketplace, composite actions y reusable workflows
ContextsEnvironments, secrets y variables de organización
Variables de entorno del proyectoSecrets y variables del repositorio
filters: brancheson.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-node en lugar de cimg/node, o mantenga una imagen con container:.
  • Las imágenes secundarias se convierten en services:. El servicio es accesible en localhost mediante el mapeo de puertos cuando el job se ejecuta directamente en el runner, y por nombre de servicio cuando el propio job usa container:. Añada un health check para que los tests no arranquen antes de que Postgres esté listo.
  • parallelism: 4 junto con circleci tests split se convierte en una matrix. CircleCI divide según tiempos registrados; el --shard de 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 production se convierte en un environment: 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

  1. Audite con el Importer y liste los orbs, contexts y pipelines programados.
  2. Porte un workflow (normalmente el job principal de pruebas) y ejecútelo en una rama.
  3. Ejecute ambos en paralelo durante una o dos semanas. Compare la duración y la tasa de aprobación; corrija las diferencias inestables.
  4. Traslade los secretos y los entornos, y después los jobs de despliegue. Pruebe primero los despliegues contra un entorno de staging.
  5. Actualice la protección de ramas para exigir los checks de GitHub en lugar de los de CircleCI.
  6. 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.

Ejecute este workflow en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis