Migrate Jenkins Pipelines (Groovy) to GitHub Actions (YAML)

Hey there, Darian Vance here. As a Senior DevOps Engineer at TechResolve, I’ve seen my fair share of CI/CD setups. For years, Jenkins was our trusty workhorse. But I can’t count the number of hours I’ve lost debugging complex Groovy scripts or wrestling with plugin compatibility issues. The final straw for me was a pipeline that failed silently on a Friday afternoon because of a subtle environment difference between my local machine and the Jenkins agent. That’s when we decided to go all-in on GitHub Actions. Putting our CI/CD logic right next to our code in the same repository was a game-changer for visibility and maintenance. It simplified our stack and, honestly, made my job more enjoyable.

Today, I want to walk you through how we migrate a standard Jenkins pipeline to GitHub Actions. This isn’t about just swapping syntax; it’s about shifting your mindset to a more declarative, repository-centric approach.

Prerequisites

Before we dive in, make sure you have the following:

• An existing Jenkins pipeline (a Jenkinsfile with Groovy script) you want to migrate.
• A GitHub repository where you have admin-level permissions to set up Actions and secrets.
• A basic comfort level with YAML syntax. It’s much simpler than Groovy, I promise.
• A general understanding of CI/CD concepts like stages, runners/agents, and artifacts.

The Step-by-Step Guide to Migration

Let’s break this down into a logical flow, mapping the concepts you already know from Jenkins to their new home in GitHub Actions.

Step 1: Deconstruct Your Jenkinsfile

First, let’s look at a typical declarative Jenkinsfile. It has a clear structure: an agent, environment variables, stages, and steps. Our goal is to map these concepts.

Here’s a simple Jenkinsfile we’ll use as our starting point:

pipeline {
    agent any

    environment {
        APP_VERSION = '1.0.0'
    }

    stages {
        stage('Build') {
            steps {
                sh 'echo "Building version ${APP_VERSION}..."'
                sh 'touch build_output.log'
            }
        }
        stage('Test') {
            steps {
                sh 'echo "Running unit tests..."'
            }
        }
    }
    post {
        always {
            archiveArtifacts artifacts: 'build_output.log'
        }
    }
}

The key Jenkins concepts here are:

• pipeline: The wrapper for the entire process. In Actions, this is a “workflow.”
• agent: The machine where the work runs. In Actions, this is a “runner.”
• environment: Global variables. In Actions, this is the `env` block.
• stage: A logical grouping of steps that run sequentially. In Actions, this translates to a “job.”
• steps: The individual commands to execute. This concept remains the same.
• post / archiveArtifacts: Actions taken after stages, like saving files. In Actions, this is usually a dedicated step using a pre-built action.

Step 2: Create Your GitHub Actions Workflow File

GitHub Actions looks for workflow definitions in a specific directory within your repository. You’ll need to create a directory named .github at the root of your project, and inside that, another directory called workflows. Inside the `workflows` directory, you can create your YAML file—let’s call it ci-pipeline.yml.

Your basic workflow file will start with a `name` and an `on` trigger, which defines when the workflow should run.

name: CI Build and Test

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

This configuration tells GitHub to run our workflow on every push or pull request to the `main` branch.

Step 3: Translate Stages to Jobs

This is the most significant conceptual shift. In Jenkins, stages run sequentially on a single agent, sharing a workspace. In GitHub Actions, jobs run in parallel by default, each on a fresh runner instance.

To make them run sequentially, you use the needs keyword. Let’s translate our ‘Build’ and ‘Test’ stages into two separate jobs.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # ... build steps go here
  
  test:
    runs-on: ubuntu-latest
    needs: build # This line is crucial! It tells GitHub to wait for 'build' to succeed.
    steps:
      # ... test steps go here

Pro Tip: I always name my jobs to clearly reflect the Jenkins stage they’re replacing. It makes the workflow graph in the GitHub UI much easier to read and immediately familiar to the rest of the team.

Step 4: Convert Steps and Use Marketplace Actions

Now, let’s fill in the `steps` for each job. The `sh` command from Jenkins becomes a `run` command in Actions. A huge advantage here is the GitHub Marketplace, which has thousands of pre-built actions.

The first step in almost every job is to check out your code, which was an implicit part of Jenkins. In Actions, we use the official actions/checkout action.

Let’s convert our full pipeline:

name: CI Build and Test

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

env:
  APP_VERSION: 1.0.0

jobs:
  build:
    name: Build Application
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Build Step
        run: |
          echo "Building version ${{ env.APP_VERSION }}..."
          touch build_output.log

      - name: Archive Build Log
        uses: actions/upload-artifact@v4
        with:
          name: build-log
          path: build_output.log

  test:
    name: Run Unit Tests
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Download Build Log
        uses: actions/download-artifact@v4
        with:
          name: build-log

      - name: Run Tests
        run: echo "Running unit tests..."

Notice a few key things:

• Environment Variables: We defined a top-level `env` block, just like in Jenkins. We reference it with the `${{ env.VAR_NAME }}` syntax.
• Artifacts: Instead of `archiveArtifacts`, we use two marketplace actions: `actions/upload-artifact` in the `build` job and `actions/download-artifact` in the `test` job. This is how you share files between jobs that run on different machines.
• Checkout: Each job needs its own `checkout` step because each one starts in a clean environment.

Where I Usually Mess Up: Common Pitfalls

Even after dozens of migrations, I still stumble sometimes. Here are the things to watch out for:

1. Forgetting that Jobs are Isolated: This is the big one. I’ve spent ages debugging why a file from my ‘build’ job wasn’t available in my ‘deploy’ job. The answer is always: I forgot to upload it as an artifact and download it in the next job. Each job is a clean slate.
2. Secrets vs. Environment Variables: Use `env` for non-sensitive data. For API keys, tokens, and passwords, always use GitHub Secrets (found in your repository’s Settings > Secrets and variables > Actions). You reference them as `${{ secrets.MY_SECRET_NAME }}`. They are securely injected and masked in logs.
3. Syntax Differences: YAML is picky about indentation. A misplaced space can invalidate the whole file. I strongly recommend using an IDE with a YAML linter (like the YAML extension for VS Code) to catch these errors before you commit.

Conclusion

Migrating from Jenkins to GitHub Actions is more than a syntax change; it’s a strategic move towards a more integrated, transparent, and maintainable CI/CD process. By mapping the concepts of agents, stages, and artifacts to runners, jobs, and marketplace actions, you can systematically translate your existing logic. The initial effort pays off immensely in reduced maintenance overhead and faster feedback loops for your development team.

It brings your automation home, right where your code lives. And in my book, that’s a massive win.

---

🤖 Frequently Asked Questions