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 CI | GitHub 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 grupo | Secrets y variables de repositorio, organización o entorno |
rules: / only / except | Disparadores on: y expresiones if: |
needs: (DAG) | needs: |
parallel: matrix | strategy.matrix |
cache: con key:files | actions/cache con hashFiles() |
artifacts: | actions/upload-artifact |
artifacts: reports: junit | Acción de reporte de tests o subida del archivo |
dependencies: (paso de artefactos) | actions/download-artifact |
extends: / include: / plantillas | Acciones compuestas, workflows reutilizables (workflow_call) |
environment: | environment: |
when: manual | Entorno con revisores obligatorios, o workflow_dispatch |
Pipelines schedule | on.schedule; consulte programaciones cron |
| GitLab Runner (tags) | Etiquetas de runner |
| Registro de contenedores | GitHub 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 consetup-*. Usecontainer: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, eslocalhostcon un puerto asignado; concontainer:es la clave del servicio. Añada una comprobación de estado (health check). cache: key: files: [poetry.lock]pasa acache: poetryensetup-python, que calcula el hash depoetry.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 disparadoronmás unif.artifacts: reports: junitno 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_callyinputs/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
- Auditoría y previsión con el Importer.
- Migre el pipeline de pruebas principal y ejecútelo en una rama.
- 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.
- Traslade los secretos, los entornos y los trabajos de despliegue. Pruebe en staging.
- Actualice la protección de ramas para exigir las comprobaciones de GitHub.
- 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.
Relacionado
- Migrar de CircleCI a GitHub Actions: paso a pasoMigre de CircleCI a GitHub Actions con tabla de equivalencias, traducción de configuración, secrets, caché, Importer y plan de 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.
- GitLab CI frente a GitHub Actions con runners de compiler.devGitLab CI frente a GitHub Actions en runners de compiler.dev: precios por puesto, minutos de cómputo y migración de .gitlab-ci.yml.
- Mejores alternativas a GitLab CI en 2026Mejores alternativas a GitLab CI en 2026: GitHub Actions, CircleCI, Buildkite, Semaphore, Jenkins y compiler.dev, con precios y notas de migración.