Saltar al contenido

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

JenkinsGitHub Actions
Jenkinsfile.github/workflows/*.yml
Multibranch pipelineWorkflow 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 / stagejobs (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, archiveArtifactsactions/upload-artifact / download-artifact
input (aprobación manual)Environment con revisores obligatorios
triggers { cron() }on.schedule
parameters { }workflow_dispatch.inputs
Bibliotecas compartidasComposite actions, reusable workflows
PluginsActions del Marketplace, o scripts sencillos
Controller de Jenkins + agentsRunners alojados por GitHub o runners autoalojados
El workspace persiste en el agentUna 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 build y test no comparten workspace. Puede volver a compilar en cada job (barato con la caché de Gradle) o pasar resultados mediante artifacts. Fusionar build dentro de los jobs de test suele ser más sencillo.
  • Las etapas parallel se convierten en una matriz o en trabajos independientes. Consulte compilaciones con matriz.
  • post { failure { mail } } se convierte en un paso de notificación con if: 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ón if:. Para la aprobación manual, añada revisores obligatorios al entorno production.
  • 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:

  1. Sustituido por una acción integrada o del marketplace (SCM, JUnit, notificaciones a Slack, credenciales, archivado de artefactos).
  2. Sustituido por un script (todo lo que envolvía una CLI).
  3. 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:

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

  1. Inventaríe los trabajos, plugins, credenciales, disparadores y quién depende de cada uno.
  2. Audite con el Importer y elija primero el pipeline más sencillo.
  3. Porte y ejecute en paralelo con Jenkins durante una o dos semanas.
  4. Traslade las credenciales y las etapas de despliegue.
  5. Cambie las comprobaciones obligatorias en la protección de ramas.
  6. 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.

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

Pruébelo gratis