Skip to content

Home / Blog / Workflows and migration

How do I migrate from Jenkins to GitHub Actions? What changes and what breaks

A factual guide to moving from Jenkins to GitHub Actions: how Jenkinsfile concepts map to a workflow, what the Actions Importer converts, and what breaks, with YAML for each.

Treat a move from Jenkins to GitHub Actions as a translation, not a copy. Each Jenkinsfile becomes a workflow file: stages become jobs, an agent becomes runs-on, and a post section has no single equivalent. GitHub’s Actions Importer converts what it can, so run its audit first, but 5 kinds of construct need hand work: scripted pipelines, secrets, self-hosted runners, build tools and plugins it does not know.

In short
  • A Jenkinsfile becomes a workflow: stages become jobs, an agent becomes runs-on, and post becomes steps with status conditions.
  • GitHub Actions Importer has audit, forecast, dry-run and migrate commands; GitHub says to inspect every converted workflow.
  • Migrate by hand: scripted pipelines, secrets, self-hosted runners, build tools and unknown plugins.
  • GitHub-hosted jobs start fresh, the Importer maps BUILD_NUMBER to run_id and not run_number, and cron has no H hash.
  • Pilot one small pipeline beside the old job before you stop it.

Jenkins is open-source software and this is a plain migration guide: it maps one tool’s concepts to the other and lists what breaks. It does not compare them. The GitHub side is from GitHub’s pages and the Jenkins side from jenkins.io, all read on the date this post was last checked.

How do Jenkins pipeline concepts map to GitHub Actions?

JenkinsGitHub ActionsNote
pipeline, a JenkinsfileA workflow file in .github/workflowsOne Jenkinsfile can become one workflow, or several.
agent { label '...' }jobs.<job_id>.runs-onA label picks a runner. Jenkins agent docker maps to jobs.<job_id>.container.
stagejobs.<job_id>Jobs run in parallel unless one needs another, so sequence them with needs.
stepsjobs.<job_id>.stepsA step runs a command or an action.
environment { ... }env on the workflow, a job or a stepCredentials are not copied: create secrets in GitHub, or use OIDC for cloud access.
options { timeout(...) }jobs.<job_id>.timeout-minutesThe default is 360 minutes. Fail-fast is strategy.fail-fast.
post { always / success / failure }A step with if: !cancelled(), success() or failure()GitHub's own table lists none. Jenkins always also runs on abort; always() does too, and GitHub advises !cancelled() instead.
parameters, inputworkflow_dispatch inputsGitHub maps both to inputs, up to 25 at the top level. A manual approval is a different feature: see the environments paragraph.
triggers { cron(...) }on.scheduleNo H hash. UTC by default (a timezone can be set), at most every 5 minutes, and may start late.
triggers { upstream(...) }needs, inside one workflowGitHub's table maps it to needs. Across workflows, the workflow_run event is the nearest.
whenjobs.<job_id>.if or steps.<step>.ifA skipped job reports Success.
tools { ... }The runner image's software, or a setup actionPrint versions on the first run.
matrix with axes and excludesstrategy.matrix with excludeGitHub's migration page lists none for excludes; the workflow syntax reference documents exclude.
Shared librariesReusable workflows and composite actionsSee the guide on choosing between them.

The rows follow GitHub’s own tables and the notes are ours, and three need a word. GitHub’s page lists “None” for Jenkins’s post section; the equivalent is a step with a status condition. Jenkins’s always becomes if: ${{ !cancelled() }}, because GitHub advises against always() for anything that could fail critically. And that page lists “None” for matrix excludes, while GitHub’s workflow syntax reference documents strategy.matrix.exclude; trust the reference. Jenkins’s shared libraries are defined in external repositories and loaded into pipelines, and the nearest GitHub equivalents are the reusable workflows and composite actions that the sharing guide compares.

What does the same pipeline look like in both?

A Jenkinsfile first, then the workflow that does the same job. The Jenkinsfile is illustrative: we did not run a Jenkins server for this post.

pipeline {
  agent { label 'linux' }
  environment { MAVEN_OPTS = '-Xmx1g' }
  options { timeout(time: 30, unit: 'MINUTES') }
  triggers { cron('H 2 * * 1-5') }
  parameters { choice(name: 'DEPLOY_ENV', choices: ['staging', 'production']) }
  stages {
    stage('Build') {
      steps { sh 'mvn --batch-mode verify' }
      post {
        always { junit 'target/surefire-reports/*.xml' }
        failure { echo "build ${env.BUILD_NUMBER} failed" }
      }
    }
    stage('Deploy') {
      when { branch 'main' }
      steps {
        input message: 'Deploy?'
        sh "./deploy.sh ${params.DEPLOY_ENV}"
      }
    }
  }
}
name: build
on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: "17 2 * * 1-5"
  workflow_dispatch:
    inputs:
      deploy-env:
        description: Where to deploy
        type: choice
        options: [staging, production]
        default: staging
permissions:
  contents: read
env:
  MAVEN_OPTS: -Xmx1g
jobs:
  build:
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-java@d1374f8ac74474200d16ef8ecee22c7ae7a51880 # v6.3.0
        with:
          distribution: temurin
          java-version: 21
          cache: maven
      - run: mvn --batch-mode verify
      - name: Archive test reports
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: surefire-reports
          path: target/surefire-reports
      - name: Tell the team
        if: ${{ failure() }}
        run: echo "build ${{ github.run_number }} failed"
  deploy:
    needs: build
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    environment: production
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - run: ./deploy.sh "$DEPLOY_ENV"
        env:
          DEPLOY_ENV: ${{ inputs.deploy-env || 'staging' }}

The workflow passes actionlint 1.7.12 and has not been run on GitHub; deploy.sh is your own script. It is a translation, not a byte for byte copy, and these are the differences to know. The Jenkinsfile declares no source control trigger, so the workflow adds push and pull_request, which is how a workflow starts on a code change. The cron minute is fixed at 17 because there is no hash. Jenkins’s timeout and environment apply to the whole pipeline, so the workflow sets the environment at the top and the timeout on each job. junit publishes parsed test results into Jenkins, and the workflow only archives the report files, which is a stand-in. The input approval becomes the production environment, where required reviewers are set in the repository’s settings and not in the file. The condition on main sits on the job, as when did on the stage. The deploy job is a fresh runner, so it checks out the code again, and anything the build made must be passed on as an artifact. And the build number is github.run_number, the count that begins at 1 and rises with each run, not the run ID.

What does GitHub Actions Importer do, and what does it leave?

It is a command line tool, distributed as a Docker container with a GitHub CLI extension, that plans and converts a migration. It has four commands for planning and converting. audit reads every pipeline on your server and writes a summary of how complete a migration can be. forecast estimates Actions usage from past builds, and needs the paginated-builds plugin on the server. dry-run writes a converted workflow to a folder, and migrate opens a pull request with it.

gh extension install github/gh-actions-importer
gh actions-importer configure
gh actions-importer audit jenkins --output-dir tmp/audit
gh actions-importer forecast jenkins --output-dir tmp/forecast
gh actions-importer dry-run jenkins --source-url my-jenkins-project --output-dir tmp/dry-run

Those commands are GitHub’s, copied from its page; we did not run them against a server. GitHub says a converted workflow should be inspected for correctness before it is used, and that the goal is an 80% conversion rate, which depends on the makeup of each pipeline. It also lists what you migrate by hand: mandatory build tools, scripted pipelines, secrets, self-hosted runners and unknown plugins. In its supported-syntax table for Jenkinsfiles, matrix, options, parameters and inputs are unsupported, so expect to write those four yourself.

What breaks in a move from Jenkins to GitHub Actions?

What breaksWhyThe fix
PluginsThere is no server to install plugins on. A step is a command or an action from a repository.List every plugin your pipelines use and find the command or action for each.
Scripted pipelinesGitHub lists them as constructs to migrate manually.Rewrite them by hand, and move logic into scripts the steps call.
CredentialsThey are not copied. A secret must be created in GitHub.Create secrets by hand, or use OIDC so a cloud credential is never stored.
The workspaceA GitHub-hosted job starts from a fresh instance. Whatever your agents kept between builds is gone.Restore dependencies with a cache, and pass files between jobs as artifacts.
Build numbersThe Importer maps BUILD_NUMBER to github.run_id, not to the sequential github.run_number.Choose on purpose which one your versions and tags need.
SchedulesNo H. A job at the start of an hour may start late.Pick a minute that is not :00.
AgentsA self-hosted runner is yours to run: GitHub says you update its operating system and software.List your agents and their labels first.

Three of these deserve a closer look. The workspace: a GitHub-hosted job starts from a fresh instance, so if your Jenkins agents kept a workspace, a Maven repository or Docker layers between builds, a workflow must restore them with a cache or build them again. The build number: the Importer’s own table maps BUILD_NUMBER to github.run_id, but a counter that rises by one per run is github.run_number. And credentials: they are never copied, and GitHub’s OIDC support lets a workflow ask a cloud provider for a short-lived token, so a cloud key need not be stored at all. If you want a person to approve a deployment, as a Jenkins input step does, GitHub’s mechanism is an environment with required reviewers: up to 6 people or teams, and one approval is enough. This is our suggestion, since GitHub’s table maps input to inputs. On Free, Pro and Team plans GitHub says required reviewers are only available for public repositories.

What changes about capacity, limits and cost?

On GitHub-hosted runners, capacity is set by plan limits: concurrent jobs are 20 on Free, 40 on Pro, 60 on Team and 500 on Enterprise for standard runners, a job stops at 6 hours, and a matrix makes at most 256 jobs. The limits post has the whole table, and the Importer’s forecast gives your past minutes to price at the rates in the pricing post. If you keep agents as self-hosted runners instead, you take on their updates and security: see what a self-hosted runner costs and the hardening guide.

In what order should you migrate?

Audit the whole server, pick one small pipeline and dry-run it, and review the workflow by hand. Run it beside the Jenkins job for a while and compare results before you stop the old one. Keep the rest of the Jenkins server until the last pipeline has moved. Once it is on GitHub, the speed guide and the small-team setup are the next two reads, and when you choose what the jobs run on, what breaks when you switch runners is the checklist. Every size we run, with its memory, disk and rate a minute, is on our managed GitHub Actions runners page.

Sources

Frequently asked questions

How do I migrate from Jenkins to GitHub Actions?

Run GitHub Actions Importer's audit to scope the work, dry-run one small pipeline, review the converted workflow by hand and run it beside the Jenkins job. Scripted pipelines, secrets, self-hosted runners, build tools and unknown plugins need manual work.

What is the equivalent of a Jenkins post section in GitHub Actions?

GitHub's migration table lists none. Use steps with status conditions: !cancelled(), success() and failure(). Jenkins's always also runs on abort, as always() does, but GitHub advises !cancelled() for steps that could fail critically.

What does GitHub Actions Importer not convert?

GitHub says you migrate mandatory build tools, scripted pipelines, secrets, self-hosted runners and unknown plugins manually. Its table marks matrix, options, parameters and inputs in a Jenkinsfile as unsupported, and says to inspect every converted workflow.

How do Jenkins cron triggers work in GitHub Actions?

Use on.schedule with POSIX cron, in UTC by default. There is no H hash for spreading load, so pick a minute. The shortest interval is 5 minutes, and runs can start late at busy times such as the start of an hour.

Move your CI onto our runners with one line

Change one line, watch your own build, then decide.

Connect GitHub

Card required. You pay only for the minutes your jobs run.

.github/workflows/ci.yml
jobs: test:removed: runs-on: ubuntu-latestadded: runs-on: runnersio-4vcpu-ubuntu-2604 steps: - uses: actions/checkout@v4 - run: make testadded: build:added: runs-on: runnersio-32vcpu-ubuntu-2604