# 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.

By Grant Unwin, published 2026-11-13. Checked against GitHub's and Jenkins's documentation on 2026-11-17. The web page: https://www.runners.io/blog/jenkins-to-github-actions-migration

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?

| Jenkins | GitHub Actions | Note |
| --- | --- | --- |
| pipeline, a Jenkinsfile | A workflow file in .github/workflows | One Jenkinsfile can become one workflow, or several. |
| agent { label '...' } | jobs.\<job\_id>.runs-on | A label picks a runner. Jenkins agent docker maps to jobs.\<job\_id>.container. |
| stage | jobs.\<job\_id> | Jobs run in parallel unless one needs another, so sequence them with needs. |
| steps | jobs.\<job\_id>.steps | A step runs a command or an action. |
| environment { ... } | env on the workflow, a job or a step | Credentials are not copied: create secrets in GitHub, or use OIDC for cloud access. |
| options { timeout(...) } | jobs.\<job\_id>.timeout-minutes | The 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, input | workflow\_dispatch inputs | GitHub 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.schedule | No H hash. UTC by default (a timezone can be set), at most every 5 minutes, and may start late. |
| triggers { upstream(...) } | needs, inside one workflow | GitHub's table maps it to needs. Across workflows, the workflow\_run event is the nearest. |
| when | jobs.\<job\_id>.if or steps.\<step>.if | A skipped job reports Success. |
| tools { ... } | The runner image's software, or a setup action | Print versions on the first run. |
| matrix with axes and excludes | strategy.matrix with exclude | GitHub's migration page lists none for excludes; the workflow syntax reference documents exclude. |
| Shared libraries | Reusable workflows and composite actions | See 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](https://www.runners.io/blog/reusable-workflows-or-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.

```text
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}"
      }
    }
  }
}
```

```yaml
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.

```bash
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 breaks | Why | The fix |
| --- | --- | --- |
| Plugins | There 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 pipelines | GitHub lists them as constructs to migrate manually. | Rewrite them by hand, and move logic into scripts the steps call. |
| Credentials | They 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 workspace | A 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 numbers | The 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. |
| Schedules | No H. A job at the start of an hour may start late. | Pick a minute that is not :00. |
| Agents | A 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](https://www.runners.io/blog/persist-build-cache-between-github-actions-runs) 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](https://www.runners.io/blog/github-actions-limits) has the whole table, and the Importer’s forecast gives your past minutes to price at the rates in the [pricing post](https://www.runners.io/blog/github-actions-pricing-2026). If you keep agents as self-hosted runners instead, you take on their updates and security: see [what a self-hosted runner costs](https://www.runners.io/blog/self-hosted-github-actions-runner-cost) and the [hardening guide](https://www.runners.io/blog/github-actions-security-hardening).

## 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](https://www.runners.io/blog/how-to-make-github-actions-faster) and the [small-team setup](https://www.runners.io/blog/best-ci-setup-small-team-github-actions) are the next two reads, and when you choose what the jobs run on, [what breaks when you switch runners](https://www.runners.io/blog/switch-github-actions-runners-what-breaks) is the checklist. Every size we run, with its memory, disk and rate a minute, is on our [managed GitHub Actions runners](https://www.runners.io/runners) page.

## Sources

- [Migrating from Jenkins to GitHub Actions](https://docs.github.com/en/actions/tutorials/migrate-to-github-actions/manual-migrations/migrate-from-jenkins)
- [Migrating from Jenkins with GitHub Actions Importer](https://docs.github.com/en/actions/tutorials/migrate-to-github-actions/automated-migrations/jenkins-migration)
- [Automating migration with GitHub Actions Importer](https://docs.github.com/en/actions/tutorials/migrate-to-github-actions/automated-migrations/use-github-actions-importer)
- [Pipeline Syntax (Jenkins)](https://www.jenkins.io/doc/book/pipeline/syntax/)
- [Extending with Shared Libraries (Jenkins)](https://www.jenkins.io/doc/book/pipeline/shared-libraries/)
- [Evaluate expressions in workflows and actions](https://docs.github.com/en/actions/reference/workflows-and-actions/expressions)
- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)
- [Events that trigger workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)
- [Contexts reference](https://docs.github.com/en/actions/reference/workflows-and-actions/contexts)
- [GitHub-hosted runners reference](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)
- [Choosing the runner for a job](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job)
- [Managing environments for deployment](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)
- [OpenID Connect](https://docs.github.com/en/actions/concepts/security/openid-connect)

## 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.
