How to Migrate from Jenkins to GitHub Actions

TL;DR

• Bottom line: Map Jenkins stages to GitHub Actions jobs, replace plugins with marketplace actions, convert Groovy DSL to YAML -- most pipelines convert in 1-2 days. Use the GitHub Actions Importer CLI for automated initial conversion.
• Key tool/command: gh actions-importer dry-run jenkins --source-url $JENKINS_URL --output-dir out/ to auto-convert, then .github/workflows/ci.yml replaces your Jenkinsfile.
• Watch out for: Jenkins shared libraries and custom Groovy have no direct equivalent -- extract logic into shell scripts or composite actions. Also: 2026 pricing changes ($0.002/min for self-hosted runners from March 2026).
• Works with: Any GitHub-hosted repo; Linux, macOS (M2 GA), Windows (Server 2025) runners; self-hosted for custom environments.

Constraints

• Pin third-party actions to full commit SHAs (not @v* tags) -- immutable actions enforcement is rolling out on hosted runners in 2026. [src8]
• Self-hosted runners on public repos must never run untrusted fork PRs -- use pull_request_target or restrict to private repos. [src6]
• GitHub Actions has a 6-hour job timeout and 72-hour workflow timeout -- restructure long-running Jenkins jobs before migrating. [src2]
• GitHub-hosted runners provide 7 GB RAM / 2 CPU / 14 GB SSD by default -- use larger runners or self-hosted for resource-intensive builds. [src2]
• Secrets must never appear in workflow YAML -- use GitHub Secrets (repo/org/environment level) and OIDC federation for cloud providers. [src2]
• Self-hosted runners now incur a $0.002/min platform charge starting March 2026 -- factor into cost analysis vs. keeping Jenkins. [src7]

Quick Reference

Decision Tree

START
├── Is the code on GitHub?
│   ├── YES -> GitHub Actions is the natural choice [src2]
│   └── NO (GitLab/Bitbucket) -> Consider platform-native CI/CD
├── How complex are Jenkins pipelines?
│   ├── Simple (build+test+deploy, <10 stages) -> Direct YAML conversion [src1]
│   ├── Moderate (10-20 stages, some shared libs) -> Use Actions Importer + composite actions [src3]
│   └── Complex (heavy shared libs, custom plugins, 20+) -> Phased migration [src3]
├── Need self-hosted runners?
│   ├── YES (GPU, special hardware) -> Set up self-hosted ($0.002/min from Mar 2026) [src6, src7]
│   └── NO -> GitHub-hosted runners [src2]
├── Multi-repo or monorepo?
│   ├── Multi-repo -> One workflow per repo [src2]
│   └── Monorepo -> Path filters + reusable workflows [src2]
├── Need automated conversion?
│   ├── YES -> Run GitHub Actions Importer for initial conversion [src3]
│   └── NO -> Manual conversion for full control
└── DEFAULT -> Start with simplest pipeline, migrate incrementally

Step-by-Step Guide

1. Audit and inventory your Jenkins pipelines

List all Jenkins jobs, their triggers, plugins, credentials, and build environments. Use the Actions Importer for an automated audit. [src3]

# Install GitHub Actions Importer
gh extension install github/gh-actions-importer

# Run audit to inventory all Jenkins pipelines
gh actions-importer audit jenkins \
  --source-url http://jenkins.example.com \
  --jenkins-access-token $JENKINS_TOKEN \
  --output-dir audit-results/

# Review the audit summary
cat audit-results/audit_summary.md

Verify: Check audit-results/ for a complete list of pipelines and their complexity ratings.

2. Map Jenkinsfile to GitHub Actions YAML

Convert Groovy DSL to YAML. Each Jenkins stage becomes a job or a group of steps. [src1]

// BEFORE: Jenkinsfile
pipeline {
    agent { docker { image 'node:20' } }
    stages {
        stage('Install') { steps { sh 'npm ci' } }
        stage('Test')    { steps { sh 'npm test' } }
        stage('Build')   { steps { sh 'npm run build' } }
        stage('Deploy') {
            when { branch 'main' }
            steps {
                withCredentials([string(credentialsId: 'deploy-token', variable: 'TOKEN')]) {
                    sh 'deploy.sh $TOKEN'
                }
            }
        }
    }
    post {
        always { junit '**/test-results/*.xml' }
        failure { slackSend channel: '#alerts', message: 'Build failed!' }
    }
}

# AFTER: .github/workflows/ci.yml
name: CI/CD Pipeline
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    container: node:20
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
      - run: npm run build
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: '**/test-results/*.xml'

  deploy:
    needs: build-and-test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh ${{ secrets.DEPLOY_TOKEN }}

  notify:
    needs: [build-and-test, deploy]
    if: failure()
    runs-on: ubuntu-latest
    steps:
      - uses: slackapi/slack-github-action@v1
        with:
          channel-id: '#alerts'
          slack-message: 'Build failed!'
        env:
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_TOKEN }}

Verify: actionlint .github/workflows/ci.yml -> no errors.

3. Migrate credentials and secrets

Move Jenkins credentials to GitHub Secrets. Use OIDC federation for cloud providers instead of long-lived keys. [src2]

# Move Jenkins credentials to GitHub Secrets
gh secret set DEPLOY_TOKEN --body "your-token-value"
gh secret set DOCKER_PASSWORD --body "your-password"

# Organization-wide secrets:
gh secret set ORG_SECRET --org my-org --body "value"

# Environment-specific secrets (staging vs production):
gh secret set AWS_ACCESS_KEY_ID --env production --body "AKIAIOSFODNN7EXAMPLE"

Verify: gh secret list -> all required secrets listed.

4. Replace Jenkins plugins with GitHub Actions

Map each Jenkins plugin to its marketplace equivalent. Pin to commit SHAs for security. [src5, src8]

# Docker build + push (Jenkins Docker plugin equivalent, pinned to SHA)
- uses: docker/setup-buildx-action@988b5a0280414f521da01fcc63a27aeeb4b104db  # v3.6.1
- uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567  # v3.3.0
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@4f58ea79222b3b9dc7c8ddd91569dbe374b16e0d  # v5.10.0
  with:
    push: true
    tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

# SonarQube Scanner (Jenkins SonarQube plugin equivalent)
- uses: SonarSource/sonarcloud-github-action@v2
  env:
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

5. Convert shared libraries to reusable workflows

Jenkins shared libraries -> GitHub reusable workflows or composite actions. [src2]

# .github/workflows/reusable-deploy.yml (in shared repo)
name: Reusable Deploy
on:
  workflow_call:
    inputs:
      environment: { required: true, type: string }
    secrets:
      deploy-token: { required: true }
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh
        env:
          TOKEN: ${{ secrets.deploy-token }}

# Usage in another repo:
jobs:
  deploy-staging:
    uses: my-org/shared-workflows/.github/workflows/reusable-deploy.yml@main
    with:
      environment: staging
    secrets:
      deploy-token: ${{ secrets.DEPLOY_TOKEN }}

Verify: gh workflow list shows the reusable workflow; calling repo triggers it successfully.

6. Run Jenkins and GitHub Actions in parallel (validation phase)

Run both systems side-by-side for 1-2 weeks before decommissioning Jenkins. Compare build outputs, timing, and test results. [src3]

# Add a comparison step to your GitHub Actions workflow
  compare-results:
    needs: [build-and-test]
    runs-on: ubuntu-latest
    steps:
      - name: Compare with Jenkins build
        run: |
          echo "GitHub Actions build: ${{ needs.build-and-test.result }}"
          echo "Compare timing, test counts, and artifact checksums with Jenkins"

Verify: Both CI systems produce identical build artifacts and test results for at least 1 week.

Code Examples

Bash: Automated Jenkinsfile to GitHub Actions converter

Full script: bash-automated-jenkinsfile-to-github-actions-conve.sh (42 lines)

#!/bin/bash
# Input:  Jenkinsfile path
# Output: Basic .github/workflows/ci.yml
set -euo pipefail
JENKINSFILE="${1:-Jenkinsfile}"
# ... (see full script)

YAML: Matrix build migration (Jenkins matrix -> GitHub Actions strategy)

# Jenkins: matrix { axes { axis { name 'OS'; values 'linux', 'windows' } } }
# GitHub Actions equivalent:
jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
      fail-fast: false
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci && npm test

YAML: OIDC authentication (replacing Jenkins cloud credentials)

# Instead of storing AWS keys as secrets, use OIDC federation
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for OIDC
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-role
          aws-region: us-east-1
      - run: aws s3 sync ./dist s3://my-bucket/

Anti-Patterns

Wrong: One massive job with all stages

# BAD -- no parallelism, slow feedback, one failure blocks everything
jobs:
  everything:
    runs-on: ubuntu-latest
    steps:
      - run: npm ci && npm test && npm run build && npm run deploy

Correct: Separate jobs with dependencies

# GOOD -- parallel where possible, clear dependencies [src2]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps: [...]
  test:
    runs-on: ubuntu-latest
    steps: [...]
  deploy:
    needs: [lint, test]  # runs after both complete
    runs-on: ubuntu-latest
    steps: [...]

Wrong: Hardcoding secrets in workflow files

# BAD -- secrets exposed in version control
env:
  API_KEY: sk-12345abcdef

Correct: Use GitHub Secrets with OIDC where possible

# GOOD -- encrypted, never logged [src2]
env:
  API_KEY: ${{ secrets.API_KEY }}
# BEST -- use OIDC for cloud providers (no stored secrets at all)
permissions:
  id-token: write

Wrong: Using floating action tags

# BAD -- @v4 can change under you, supply chain risk [src8]
- uses: actions/checkout@v4

Correct: Pin actions to commit SHAs

# GOOD -- immutable, auditable, matches upcoming enforcement [src8]
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

Wrong: Running self-hosted runners on public repos without restrictions

# BAD -- any fork PR can execute arbitrary code on your runner [src6]
on: pull_request
jobs:
  build:
    runs-on: self-hosted

Correct: Restrict self-hosted runners to trusted events

# GOOD -- only trigger on internal events [src6]
on:
  push:
    branches: [main]
  pull_request_target:
    branches: [main]
jobs:
  build:
    runs-on: self-hosted
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository

Common Pitfalls

• Shared libraries have no 1:1 equivalent: Extract Groovy logic into shell scripts or composite actions. Reusable workflows handle orchestration but cannot contain arbitrary Groovy. [src1, src3]
• Jenkins when conditions more flexible: GitHub Actions if: covers most cases but cannot match complex Groovy conditionals. Fix: use job-level outputs and multi-step conditionals. [src1]
• Artifact passing differs: Jenkins stash/unstash is within one pipeline. GitHub needs explicit upload/download between jobs. [src2]
• Cron syntax differences: Jenkins uses H for hash distribution; GitHub uses standard cron. Replace H with specific minutes. [src1]
• Self-hosted runner security: GitHub self-hosted runners on public repos can execute code from any fork PR. Fix: use pull_request_target or restrict to private repos. [src6]
• No built-in pipeline visualization: Jenkins Blue Ocean provides visual progress. Fix: use descriptive job/step names and group steps with composite actions. [src1]
• 2026 pricing changes surprise: Self-hosted runners now cost $0.002/min from March 2026. Fix: audit runner usage and factor into ROI analysis. [src7]
• Actions Importer output needs review: The automated converter produces functional but not optimal YAML. Fix: always review -- merge redundant jobs, add caching, pin action versions. [src3]

Diagnostic Commands

# Analyze Jenkinsfile complexity
grep -c "stage\|step\|when\|parallel" Jenkinsfile

# List all Jenkins plugins used (Jenkins CLI)
java -jar jenkins-cli.jar -s http://jenkins:8080/ list-plugins

# Run GitHub Actions Importer dry-run
gh actions-importer dry-run jenkins \
  --source-url http://jenkins.example.com \
  --output-dir dry-run-results/

# Validate GitHub Actions workflow
actionlint .github/workflows/ci.yml

# List workflows and recent runs
gh workflow list && gh run list --limit 10

# Check self-hosted runner status
gh api /repos/{owner}/{repo}/actions/runners

# View workflow run logs
gh run view <run-id> --log

# Check GitHub Actions billing usage
gh api /orgs/{org}/settings/billing/actions

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• GitHub Actions has a 6-hour job timeout and 72-hour workflow timeout. Long-running Jenkins jobs may need restructuring.
• GitHub-hosted runners: 7 GB RAM, 2 CPU, 14 GB SSD. Complex builds may need larger runners ($$$) or self-hosted. Larger runners (up to 64 CPU) available on Team and Enterprise plans.
• Free tier: 2,000 minutes/month for private repos. Hosted runner prices reduced up to 39% in January 2026. Large orgs should compare total cost vs. self-hosted Jenkins. [src7]
• Jenkins plugins with side effects (modifying Jenkins config, managing agents) have no equivalent -- those are Jenkins admin features.
• 67% of organizations using Jenkins as primary CI/CD in 2022 have migrated away or are in process (2024 State of DevOps Report).
• GitHub Actions Importer can automate initial conversion but output needs manual review and optimization. [src3]
• Agentic workflows (AI-powered automation in GitHub Actions) are in technical preview as of February 2026 -- not yet production-ready.