Migrar de Jenkins a GitHub Actions: paso a paso
Última actualización
Migrar de Jenkins a GitHub Actions significa traducir un Jenkinsfile a YAML de workflow: las stages se convierten en jobs o steps, agent pasa a ser runs-on, las credenciales pasan a ser secrets y las bibliotecas compartidas se convierten en composite actions o reusable workflows. Los pipelines declarativos se traducen bien. Los pipelines scripted con mucha lógica en Groovy son la parte que más tiempo requiere. Esta guía ofrece la correspondencia entre ambos, una traducción completa de ejemplo, qué hacer con los agents y los plugins, y un plan de transición.
Páginas relacionadas: Jenkins frente a GitHub Actions y alternativas a Jenkins.
Equivalencia de conceptos
| Jenkins | GitHub Actions |
|---|---|
Jenkinsfile | .github/workflows/*.yml |
| Multibranch pipeline | Workflow on: push / pull_request (se ejecuta automáticamente por rama) |
agent { label 'x' } | runs-on: [label] |
agent { docker { image 'x' } } | container: x en el job |
stages / stage | jobs (en paralelo por defecto) o steps secuenciales |
parallel { } | Jobs independientes, o una matrix |
steps { sh '...' } | steps: - run: ... |
environment { } | env: a nivel de workflow, job o step |
credentials('id') | ${{ secrets.NAME }} |
when { branch 'main' } | if: github.ref == 'refs/heads/main' |
post { always { } } | Step con if: always() |
stash / unstash, archiveArtifacts | actions/upload-artifact / download-artifact |
input (aprobación manual) | Environment con revisores obligatorios |
triggers { cron() } | on.schedule |
parameters { } | workflow_dispatch.inputs |
| Bibliotecas compartidas | Composite actions, reusable workflows |
| Plugins | Actions del Marketplace, o scripts sencillos |
| Controller de Jenkins + agents | Runners alojados por GitHub o runners autoalojados |
| El workspace persiste en el agent | Una VM nueva por job, salvo que use caché o un runner persistente |
Esa última fila es la que más sorprende. Un agent de Jenkins suele conservar su workspace, el repositorio de Maven y las capas de Docker entre compilaciones. Un runner alojado de GitHub empieza vacío en cada job, así que necesita caché explícita para recuperar la velocidad.
Un pipeline realista, en paralelo
Un Jenkinsfile declarativo para un servicio Java:
pipeline {
agent { label 'linux' }
options { timeout(time: 30, unit: 'MINUTES') }
environment {
REGISTRY = 'registry.example.com'
DEPLOY_KEY = credentials('deploy-key')
}
stages {
stage('Build') {
steps { sh './gradlew assemble' }
}
stage('Test') {
parallel {
stage('Unit') { steps { sh './gradlew test' } }
stage('Integration') { steps { sh './gradlew integrationTest' } }
}
post { always { junit '**/build/test-results/**/*.xml' } }
}
stage('Deploy') {
when { branch 'main' }
steps { sh './scripts/deploy.sh' }
}
}
post { failure { mail to: 'team@example.com', subject: 'Build failed' } }
}
La versión para GitHub Actions:
name: CI
on:
push:
branches: [main]
pull_request:
env:
REGISTRY: registry.example.com
jobs:
build:
runs-on: ubuntu-latest # or [self-hosted, Linux, compiler-ci]
timeout-minutes: 30
steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- uses: gradle/actions/setup-gradle@v6
- run: ./gradlew assemble
test:
needs: build
runs-on: ubuntu-latest
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
task: [test, integrationTest]
steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- uses: gradle/actions/setup-gradle@v6
- run: ./gradlew ${{ matrix.task }}
- uses: actions/upload-artifact@v4
if: always()
with:
name: results-${{ matrix.task }}
path: "**/build/test-results/**/*.xml"
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_KEY: ${{ secrets.DEPLOY_KEY }}
Notas sobre la traducción:
- Cada job de GitHub se ejecuta en una máquina nueva, así que
buildytestno comparten workspace. Puede volver a compilar en cada job (barato con la caché de Gradle) o pasar resultados mediante artifacts. Fusionarbuilddentro de los jobs de test suele ser más sencillo. - Las etapas
parallelse convierten en una matriz o en trabajos independientes. Consulte compilaciones con matriz. post { failure { mail } }se convierte en un paso de notificación conif: failure(), o bien puede usar las notificaciones integradas de GitHub para flujos de trabajo fallidos.credentials('deploy-key')se convierte en un secreto. Créelo en el repositorio, en la organización o en un entorno.when { branch 'main' }se convierte en una condiciónif:. Para la aprobación manual, añada revisores obligatorios al entornoproduction.- Los resultados de las pruebas se suben como artefactos. Para ver un resumen en la pull request, use una acción de informe JUnit.
Agentes, etiquetas y alojamiento propio
Muchas organizaciones que usan Jenkins ejecutan sus propios agentes por una razón concreta: acceso a redes privadas, hardware especial o coste. GitHub Actions admite runners autoalojados con etiquetas, que se corresponden con las etiquetas de Jenkins. Los runners alojados no pueden acceder a redes privadas sin un túnel o un enfoque como OIDC con un endpoint público. Si necesita acceso privado, planifique runners autoalojados y lea las notas de seguridad: nunca ejecute código no confiable de forks en un runner de larga duración.
Si migró a runners alojados por GitHub y las compilaciones se han vuelto más lentas que en sus agentes de Jenkins, normalmente se debe a la configuración predeterminada de 2 vCPU y a una caché fría. compiler.dev ejecuta los mismos trabajos en máquinas de 8 vCPU / 16 GB con cachés de dependencias y de capas de Docker preparadas, a $0.008 por minuto, mediante runs-on: [self-hosted, Linux, compiler-ci], con un respaldo automático a sus runners originales; consulte precios y runners más rápidos.
Plugins
Audite los plugins instalados y clasifíquelos en tres grupos:
- Sustituido por una acción integrada o del marketplace (SCM, JUnit, notificaciones a Slack, credenciales, archivado de artefactos).
- Sustituido por un script (todo lo que envolvía una CLI).
- Sin equivalente (plugins poco frecuentes que extienden la interfaz de Jenkins). Decida si todavía los necesita.
Revise las acciones del marketplace antes de adoptarlas: fije las acciones de terceros a un SHA de commit, tal como se explica en cómo proteger GitHub Actions.
Credenciales y secretos
Jenkins almacena las credenciales en el controlador, y no es posible exportar los valores secretos desde la interfaz. Obténgalos de su gestor de contraseñas o de su bóveda y añádalos como secretos de GitHub. Sustituya las claves de nube de larga duración por OIDC siempre que sea posible: OIDC de GitHub Actions con AWS. Los secretos del ámbito global del controlador se convierten en secretos de organización; las credenciales por carpeta se convierten en secretos de repositorio o de entorno.
Caché
Los agentes de Jenkins solían cachear porque eran de larga duración. En Actions, añada la caché de forma explícita:
- Gradle: cache-gradle-github-actions (la acción
setup-gradleanterior ya lo hace). - npm, pnpm, Yarn: npm, pnpm, Yarn.
- Docker: caché de capas de Docker y caché de buildx.
- Reglas generales y el límite de 10 GB: guía de caché.
Conversión automatizada: GitHub Actions Importer
El Importer de GitHub es una extensión de gh. Según la documentación de GitHub (consultada en octubre de 2026), admite Jenkins, CircleCI, GitLab CI, 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 jenkins --output-dir audit --source-url https://jenkins.example.com
Los comandos documentados son audit, forecast, dry-run y migrate. Empiece con audit sobre su servidor de Jenkins para obtener un informe de lo que se convierte y lo que no, y después use dry-run para generar los flujos de trabajo en local. Prevea convertir a mano las bibliotecas compartidas, el Groovy personalizado y los pasos específicos de plugins. Consulte la documentación actual del Importer de GitHub para conocer los parámetros exactos con Jenkins, ya que las credenciales y las URL se pasan de forma distinta que en otras plataformas.
Plan de transición
- Inventaríe los trabajos, plugins, credenciales, disparadores y quién depende de cada uno.
- Audite con el Importer y elija primero el pipeline más sencillo.
- Porte y ejecute en paralelo con Jenkins durante una o dos semanas.
- Traslade las credenciales y las etapas de despliegue.
- Cambie las comprobaciones obligatorias en la protección de ramas.
- Congele los trabajos de Jenkins (solo lectura), conserve el controlador durante un ciclo de publicación para tener el historial y, después, retírelo.
Preguntas frecuentes
¿GitHub Actions puede reemplazar por completo a Jenkins?
Para la mayoría de los pipelines de compilación, pruebas y despliegue, sí. Mantenga Jenkins cuando dependa de un plugin sin equivalente o necesite funciones a nivel de controlador.
¿Cómo reemplazo las bibliotecas compartidas de Jenkins?
Use acciones compuestas para los pasos reutilizables y flujos de trabajo reutilizables para pipelines completos. Convierta la lógica de Groovy a shell o a un script pequeño.
¿Qué pasa con los agentes de Jenkins en redes privadas?
Use runners autoalojados dentro de esa red con etiquetas equivalentes.
¿La persistencia del workspace de Jenkins supone un problema?
Puede serlo. Añada caché o use runners que mantengan las cachés activas, en lugar de depender de archivos sobrantes.
¿Cuánto tiempo lleva?
Un pipeline declarativo sencillo: unas horas. Decenas de pipelines scripted y plugins: planifique semanas, sobre todo para la validación.
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 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.
- Jenkins frente a GitHub Actions con runners de compiler.devJenkins vs. GitHub Actions en runners de compiler.dev: sin coste de licencia frente al coste operativo real, y migración de Jenkinsfile a workflow.
- Mejores alternativas a Jenkins en 2026Mejores alternativas a Jenkins en 2026: GitHub Actions, GitLab CI, Buildkite, CircleCI, Semaphore y compiler.dev, con notas de migración desde Jenkinsfile.