Saltar al contenido

Migrar de GitLab CI a GitHub Actions: paso a paso

Última actualización

Migrar GitLab CI a GitHub Actions es una traducción bastante directa. Las stages se convierten en needs, las rules pasan a on junto con if, cache y artifacts se corresponden con actions/cache y upload-artifact, y los services se mantienen como services. Los puntos más delicados son include y extends (use workflows reutilizables y acciones compuestas), las variables de CI/CD (los secrets no se exportan) y las funciones exclusivas de GitLab, como el registro de contenedores integrado y las Review Apps.

Páginas relacionadas: GitLab CI frente a GitHub Actions y alternativas a GitLab CI.

Equivalencia de conceptos

GitLab CIGitHub Actions
.gitlab-ci.yml.github/workflows/*.yml
stages:Orden de los jobs con needs:
job:jobs.<id>
image:container: en el job, o use acciones setup-*
services:services:
script:steps: - run:
before_script: / after_script:Pasos anteriores, o pasos con if: always()
variables:env:
Variables de CI/CD del proyecto o del grupoSecrets y variables de repositorio, organización o entorno
rules: / only / exceptDisparadores on: y expresiones if:
needs: (DAG)needs:
parallel: matrixstrategy.matrix
cache: con key:filesactions/cache con hashFiles()
artifacts:actions/upload-artifact
artifacts: reports: junitAcción de reporte de tests o subida del archivo
dependencies: (paso de artefactos)actions/download-artifact
extends: / include: / plantillasAcciones compuestas, workflows reutilizables (workflow_call)
environment:environment:
when: manualEntorno con revisores obligatorios, o workflow_dispatch
Pipelines scheduleon.schedule; consulte programaciones cron
GitLab Runner (tags)Etiquetas de runner
Registro de contenedoresGitHub Packages (ghcr.io) u otro registro
$CI_COMMIT_SHA, $CI_COMMIT_BRANCH${{ github.sha }}, ${{ github.ref_name }}

Un pipeline realista, en paralelo

GitLab:

# .gitlab-ci.yml
stages: [build, test, deploy]

default:
  image: python:3.13
  cache:
    key:
      files: [poetry.lock]
    paths: [.cache/pip]

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

build:
  stage: build
  script:
    - pip install poetry
    - poetry build
  artifacts:
    paths: [dist/]
    expire_in: 1 week

test:
  stage: test
  parallel:
    matrix:
      - PYVER: ["3.12", "3.13"]
  image: python:$PYVER
  services:
    - postgres:16
  variables:
    POSTGRES_PASSWORD: postgres
    DATABASE_URL: postgres://postgres:postgres@postgres:5432/postgres
  script:
    - pip install -r requirements.txt
    - pytest --junitxml=report.xml
  artifacts:
    when: always
    reports:
      junit: report.xml

deploy:
  stage: deploy
  script: ./scripts/deploy.sh
  environment: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  needs: [test]

GitHub Actions:

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest        # or [self-hosted, Linux, compiler-ci]
    steps:
      - uses: actions/checkout@v6
      - run: pipx install poetry
      - uses: actions/setup-python@v7
        with:
          python-version: "3.13"
          cache: poetry
      - run: poetry build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 7

  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python: ["3.12", "3.13"]
    services:
      postgres:
        image: postgres:16
        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-python@v7
        with:
          python-version: ${{ matrix.python }}
          cache: pip
      - run: pip install -r requirements.txt
      - run: pytest --junitxml=report.xml
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: junit-${{ matrix.python }}
          path: report.xml

  deploy:
    needs: [build, 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

Qué debe tener en cuenta:

  • GitLab ejecuta cada job en la image:. En Actions el job se ejecuta en la VM del runner, y usted instala el lenguaje con setup-*. Use container: cuando necesite una imagen específica.
  • Services: en GitLab el host del servicio es el nombre de la imagen (postgres). En Actions, con el job en el runner, es localhost con un puerto asignado; con container: es la clave del servicio. Añada una comprobación de estado (health check).
  • cache: key: files: [poetry.lock] pasa a cache: poetry en setup-python, que calcula el hash de poetry.lock. Consulte caché de Poetry, caché de pip y la guía general de caché.
  • rules: if: $CI_COMMIT_BRANCH == "main" se convierte en el disparador on más un if.
  • artifacts: reports: junit no tiene un equivalente directo; suba el archivo o use una acción de reporte JUnit.

Variables, secrets y entornos

GitLab variables marked masked or protected become GitHub secrets. Protected variables, available only on protected branches, map to environment secrets with branch protection rules on the environment. You must copy values manually; there is no export of secret values. File-type variables become secrets you write to a file in a step. Predefined CI_ variables map to GitHub contexts (github., runner.*).

Para las credenciales de la nube, OIDC sustituye a las claves almacenadas: OIDC de GitHub Actions con AWS. Más medidas de seguridad en cómo proteger GitHub Actions.

Include, extends y plantillas

Los pipelines de GitLab suelen compartir YAML mediante include: y extends:. Elija el mecanismo de Actions según el tamaño:

  • Una secuencia de pasos compartida: una acción compuesta en un repositorio común.
  • Un trabajo o pipeline completo compartido: un workflow reutilizable con on: workflow_call y inputs/secrets.
  • Plantillas con muchas personalizaciones: workflows reutilizables con inputs o un enfoque de YAML generado.

Los workflows reutilizables no pueden hacer todo lo que extends permite (por ejemplo, la fusión profunda de claves arbitrarias), así que espere tener que reestructurar en lugar de traducir.

Lo que GitLab incluye y GitHub no

  • Registro de contenedores: use GitHub Packages (ghcr.io) o un registro externo.
  • Review Apps y panel de entornos: los Environments y deployments de GitHub cubren una parte; los entornos de vista previa requieren su propia configuración.
  • Plantillas integradas de análisis de seguridad: GitHub dispone de code scanning y Dependabot; consulte la configuración de Dependabot.
  • Merge trains: el equivalente en GitHub es la merge queue.
  • Pipelines hijos y pipelines dinámicos: use llamadas a workflows y estrategias matrix.

Conversión automatizada: GitHub Actions Importer

El Importer de GitHub es una extensión de gh. Según la documentación de GitHub (revisada en octubre de 2026), admite GitLab (en la nube y autoalojado), Jenkins, CircleCI, Azure DevOps, Bamboo, Bitbucket Pipelines y Travis CI, y requiere Docker y la CLI de GitHub.

gh extension install github/gh-actions-importer
gh actions-importer configure
gh actions-importer audit gitlab --output-dir audit --namespace my-group

Los comandos documentados son audit, forecast, dry-run y migrate. Ejecute audit para obtener un resumen de lo que se convierte, forecast para estimar los minutos de Actions a partir de su historial de pipelines de GitLab y, después, dry-run para generar los workflows en local. Consulte la documentación del Importer de GitHub para conocer las opciones que necesita su configuración de GitLab. Trate el resultado como un borrador: las estructuras include/extends en particular requieren revisión.

Plan de transición

  1. Auditoría y previsión con el Importer.
  2. Migre el pipeline de pruebas principal y ejecútelo en una rama.
  3. Mantenga ambos durante un tiempo: deje GitLab CI en funcionamiento y compare resultados. Si mantiene el código en GitLab durante esta fase, tenga en cuenta que Actions necesita el repositorio en GitHub; planifique el traslado del repositorio como un paso aparte.
  4. Traslade los secretos, los entornos y los trabajos de despliegue. Pruebe en staging.
  5. Actualice la protección de ramas para exigir las comprobaciones de GitHub.
  6. Desactive GitLab CI y archive la configuración antigua.

Velocidad después de la migración

Los runners compartidos de GitLab y los runners predeterminados de GitHub de 2 vCPU tienen tamaños distintos; compárelos antes de sacar conclusiones. Los runners grandes de GitHub cuestan más; consulte los precios de GitHub Actions. compiler.dev ejecuta los mismos workflows en máquinas de 8 vCPU / 16 GB a $0.008 por minuto mediante runs-on: [self-hosted, Linux, compiler-ci], con recurso automático a sus runners originales; consulte precios y runners más rápidos.

Preguntas frecuentes

¿Tengo que trasladar mi repositorio de GitLab a GitHub?

Sí, GitHub Actions funciona con repositorios alojados en GitHub. Planifique la migración del código junto con la migración de CI.

¿Cómo sustituyo include y extends de GitLab?

Acciones compuestas para los pasos compartidos y workflows reutilizables para los trabajos compartidos.

¿Las variables de GitLab CI se migran automáticamente?

No. Los valores de los secretos no se pueden exportar; vuelva a introducirlos como secretos de GitHub.

¿Qué sustituye al paso de artefactos entre etapas de GitLab?

upload-artifact en un trabajo y download-artifact en el siguiente, con needs.

¿Puedo ejecutar ambos sistemas de CI durante la migración?

Sí, en un repositorio duplicado o espejo, y compare los resultados antes de cambiar las comprobaciones obligatorias.

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

Pruébelo gratis