jenkins

jenkins Best Practices

This guide outlines essential best practices for developing Jenkins Pipelines. Adhere to these rules to ensure your CI/CD processes are efficient, secure, and maintainable.

1. Code Organization and Structure

1.1. Always use "Pipeline as Code"

Store your Jenkinsfile in the root of your project's SCM repository. This enables version control, peer review, and a traceable history for your pipeline definitions.

❌ BAD: Defining pipelines directly in the Jenkins UI.

// No Jenkinsfile in SCM, pipeline defined in UI.
// Hard to track changes, no version history.

✅ GOOD: Store Jenkinsfile in SCM.

// Jenkinsfile at project root (e.g., my-app/Jenkinsfile)
pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

1.2. Prefer Declarative Pipeline Syntax

Declarative syntax is more readable, structured, and offers built-in validation. Use it for all new pipelines unless a specific, advanced scenario absolutely requires Scripted syntax.

❌ BAD: Using Scripted Pipeline for standard CI/CD flows.

// Scripted Pipeline (less readable, harder to validate)
node('agent-label') {
    stage('Checkout') {
        checkout scm
    }
    stage('Build') {
        sh 'npm install'
        sh 'npm run build'
    }
}

✅ GOOD: Use Declarative Pipeline Syntax.

// Declarative Pipeline (structured, readable, validated)
pipeline {
    agent { label 'agent-label' }
    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        stage('Build') {
            steps {
                sh 'npm install'
                sh 'npm run build'
            }
        }
    }
}

1.3. Leverage Shared Libraries for Reusability

Extract common, complex, or security-sensitive logic into Jenkins Shared Libraries. This promotes code reuse, centralizes maintenance, and keeps Jenkinsfiles clean and focused on orchestration. Avoid script tags in Declarative Pipelines; they are a strong indicator that a shared library is needed.