Pipeline Best Practices

This lesson covers

The 12 pipeline best practices — structure, performance, security, maintainability, and the anti-patterns that turn a good pipeline into a maintenance nightmare

A Jenkinsfile that's 800 lines of Groovy is a pipeline no one wants to maintain. The Jenkinsfile should read like a recipe — it describes the steps at a high level. Complex logic (data processing, dynamic stage generation, conditional trees) belongs in shell scripts or shared library functions that the Jenkinsfile calls.

If a commit has a syntax error, you want to know in 30 seconds, not after a 10-minute Docker build. Order your stages so the fastest, cheapest checks run first. A developer gets faster feedback, and a failing build wastes the minimum amount of compute.

This was covered in Lesson 18 but it's important enough to repeat in the best practices list. A Jenkinsfile committed to Git carries its history forever. A hardcoded API key, password, or token in a Jenkinsfile is a permanent security risk — even if you remove it in the next commit.

A hung pipeline ties up an agent executor indefinitely. Without a timeout, a network hiccup or a deadlocked process silently blocks your CI system until someone notices — which might be the next morning. Every pipeline should have a global timeout in its options { } block.

options {
    timeout(time: 30, unit: 'MINUTES')  // kill the pipeline if it runs longer than this
    buildDiscarder(logRotator(numToKeepStr: '20'))
    timestamps()
    disableConcurrentBuilds()
}

If unit tests, integration tests, and static analysis don't depend on each other, there's no reason to run them sequentially. Running them in parallel cuts pipeline time by as much as the longest single stage — often saving 3–5 minutes per build. On a team that pushes code 20 times a day, that's an hour of developer waiting time saved every day.

stage('Run All Checks in Parallel') {
    parallel {
        stage('Unit Tests')        { steps { sh './gradlew test' } }
        stage('Integration Tests') { steps { sh './gradlew integrationTest' } }
        stage('Static Analysis')   { steps { sh './gradlew checkstyle pmd' } }
    }
}

Without workspace cleanup, every build leaves files behind on the agent. Over weeks of active development, agent disks fill up and builds start failing with "No space left on device" at 3 AM. Put cleanWs() in post { always { } } — it runs whether the build passed or failed.

post {
    always {
        cleanWs()  // deletes the workspace after every build, pass or fail
    }
}

If tests fail and you don't publish the results, you've lost the most important diagnostic information at the exact moment you need it most. Use a stage-level post { always { junit '...' } } block — not a pipeline-level one. That way, results are published immediately when the test stage finishes, even if a subsequent deploy stage fails.

stage('Test') {
    steps { sh './gradlew test' }
    post {
        always {
            // publish test results even if tests failed — you need this most when they do
            junit allowEmptyResults: true, testResults: 'build/test-results/**/*.xml'
        }
    }
}

Using image: 'node:latest' as your build environment means your pipeline silently changes behaviour every time the Node.js team releases a new version. Pin to a specific tag — node:20-alpine — so your build environment only changes when you consciously decide to upgrade it.

This was covered in Lesson 20 but belongs in the best practices list. Notifying on every passing build trains the team to ignore notifications. Notifying only on failures and recoveries means every notification is actionable. Use the currentBuild.previousBuild?.result pattern to detect state changes.

post {
    failure { slackSend(channel: '#ci', color: 'danger', message: "❌ Build failed") }
    success {
        script {
            // Only notify on recovery — stay silent when already green
            if (currentBuild.previousBuild?.result == 'FAILURE') {
                slackSend(channel: '#ci', color: 'good', message: "✅ Build fixed")
            }
        }
    }
}

Putting conditional logic inside sh commands or script { if } blocks hides what the pipeline is doing. When a stage is skipped by a when condition, Jenkins shows "skipped due to when condition" in the stage view — visible at a glance. When it's hidden in a script block, the stage appears to run and readers have to dig into logs to understand what happened.

steps {
  script {
    if (env.BRANCH_NAME == 'main') {
      sh './deploy.sh'
    }
  }
}

when { branch 'main' }
steps {
  sh './deploy.sh'
}

Covered in Lesson 12, worth repeating here as a practice. Declarative syntax is readable by engineers who don't know Groovy. It validates before running. It has built-in post, when, and options directives. Use script { } when you need Groovy logic. Only reach for full Scripted when you've genuinely hit Declarative's limits — which is rare.

A Jenkinsfile in a repository gets reviewed in pull requests, versioned with the code it builds, and recovered automatically if Jenkins dies. A pipeline configured only in the Jenkins UI is a single point of failure. This isn't just a best practice — it's the entire point of pipeline-as-code. If your team is still using Freestyle jobs in production, this is the most impactful change you can make.

What just happened?

• Lint ran first — the cheapest check passed in seconds. If it had failed, the parallel test stage would never have started, saving several minutes of compute.
• Unit and integration tests ran simultaneously — both test suites executed in parallel. Total wall time was determined by the slower one (integration tests), not the sum of both. Practice 5 in action.
• Both junit blocks fired in stage-level post — test results were published immediately after each parallel branch finished, not at the end of the pipeline. Practice 7 in action.
• Build description set to main · 71-d4e5f6a — visible in the Jenkins build history as a subtitle. The build history page is now actually useful — you can see at a glance which branch and commit each build represents.
• No "fixed" notification sent — the previous build was SUCCESS, so previousBuild.result == 'FAILURE' was false and the fixed notification was suppressed. Only the deploy notification fired. Practice 9 in action.
• cleanWs() ran in always post — workspace deleted. Agent disk stays clean. Practice 6 in action.

Where to start: Copy this Jenkinsfile into your repository. Delete the Build Image and Deploy Staging stages if you're not using Docker or Kubernetes yet. Keep the structure, the options block, the parallel test stages, and the post block. Those four things alone put your pipeline ahead of 80% of what teams ship in production. Extend from there.

Teacher's Note

The reference Jenkinsfile above is your Section II graduation project. If you can read every line of it and explain what it does and why — you're ready for Section III.

Up Next · Section III · Lesson 26

Plugins Overview

Section II is complete. Section III begins — security, plugins, and scaling. First stop: the plugin ecosystem that makes Jenkins what it is.