Jenkins: Declarative Pipelines, Stages, Agents and Secrets Reference Guide

# 1. Run Jenkins LTS in Docker with persistent state
docker volume create jenkins_home

docker run -d --name jenkins \
    -p 8080:8080 -p 50000:50000 \
    -v jenkins_home:/var/jenkins_home \
    -v /var/run/docker.sock:/var/run/docker.sock \
    jenkins/jenkins:lts-jdk21

# 2. Initial admin password
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

# 3. Pre-install plugins from a plugins.txt (one per line: short-name[:version])
cat > plugins.txt <<'TXT'
workflow-aggregator
configuration-as-code
github-branch-source
docker-workflow
kubernetes
credentials-binding
htmlpublisher
junit
blueocean
TXT

docker exec jenkins \
    jenkins-plugin-cli --plugin-file /tmp/plugins.txt \
                       --plugin-download-directory /var/jenkins_home/plugins

# 4. Configuration-as-Code — declarative instance config
#    point Jenkins at it via env var
docker exec jenkins \
    env CASC_JENKINS_CONFIG=/var/jenkins_home/casc.yaml || true
# casc.yaml: define security realm, credentials, jobs, tools — all in YAML

# 5. CLI from outside
java -jar jenkins-cli.jar -s http://localhost:8080/ -auth admin:**** list-jobs

// Jenkinsfile — declarative pipeline at repo root.
pipeline {
    agent { label 'linux && docker' }

    options {
        timeout(time: 30, unit: 'MINUTES')
        buildDiscarder(logRotator(numToKeepStr: '20'))
        disableConcurrentBuilds()
        ansiColor('xterm')
    }

    parameters {
        choice(name: 'TARGET_ENV', choices: ['dev', 'stg', 'prod'], description: 'deploy target')
        booleanParam(name: 'RUN_E2E', defaultValue: false)
    }

    environment {
        REGISTRY = 'ghcr.io/my-org'
        APP      = 'web'
    }

    triggers {
        githubPush()
        cron('H 2 * * 1-5')              // weekday early-morning rebuilds
    }

    stages {
        stage('Build') {
            steps { sh 'make build' }
        }

        stage('Test') {
            parallel {
                stage('unit') { steps { sh 'pytest --junitxml=junit.xml' } }
                stage('lint') { steps { sh 'ruff check .' } }
            }
            post { always { junit 'junit.xml' } }
        }

        stage('Deploy') {
            when { branch 'main'; beforeAgent true }
            steps {
                input message: "Deploy to ${params.TARGET_ENV}?", ok: 'Go'
                sh "./deploy.sh ${params.TARGET_ENV}"
            }
        }
    }

    post {
        always  { archiveArtifacts artifacts: 'build/*.zip', fingerprint: true }
        failure { slackSend channel: '#ci-alerts', message: "Pipeline FAILED: ${env.BUILD_URL}" }
    }
}

// Scripted pipeline — Groovy with full programmability.
// Use when declarative isn't expressive enough (rare).
node('linux && docker') {

    try {
        stage('Checkout') {
            checkout scm
        }

        stage('Build') {
            // Run inside a container without losing the workspace
            docker.image('maven:3.9-eclipse-temurin-21').inside('-v $HOME/.m2:/root/.m2') {
                sh 'mvn -B -DskipTests package'
            }
        }

        // Parallel scripted stages
        stage('Verify') {
            parallel(
                unit:        { sh 'mvn test' },
                integration: { sh 'mvn verify -DskipUnitTests' },
                lint:        { sh 'mvn spotbugs:check' },
                failFast: true,
            )
        }

        stage('Publish') {
            if (env.BRANCH_NAME == 'main') {
                withCredentials([usernamePassword(
                    credentialsId: 'ghcr',
                    usernameVariable: 'U', passwordVariable: 'P')]) {
                    sh 'echo $P | docker login ghcr.io -u $U --password-stdin'
                    sh 'docker push ghcr.io/my-org/app:${BUILD_NUMBER}'
                }
            } else {
                echo "Skipping publish on branch ${env.BRANCH_NAME}"
            }
        }
    }
    catch (err) {
        currentBuild.result = 'FAILURE'
        throw err
    }
    finally {
        junit testResults: '**/target/surefire-reports/*.xml', allowEmptyResults: true
    }
}

// Shared library layout (separate Git repo):
//   vars/
//     deployApp.groovy          // exposed as a global step
//   src/
//     org/example/Builder.groovy
//   resources/
//     templates/dockerfile.tpl  // libraryResource('templates/dockerfile.tpl')

// vars/deployApp.groovy
def call(Map cfg = [:]) {
    def env  = cfg.get('env',  'dev')
    def app  = cfg.get('app',  env.JOB_NAME)
    def wait = cfg.get('wait', true)

    stage("Deploy ${app} → ${env}") {
        withCredentials([file(credentialsId: "kube-${env}", variable: 'KUBECONFIG')]) {
            sh "kubectl apply -f k8s/${env}/"
            if (wait) {
                sh "kubectl rollout status deployment/${app} --timeout=5m"
            }
        }
    }
}

// Jenkinsfile in the consuming repo — pin the library to a tag for reproducibility.
@Library('platform-shared@v1.4.0') _

pipeline {
    agent any
    stages {
        stage('Build')  { steps { sh 'make build' } }
        stage('Deploy') {
            when { branch 'main' }
            steps {
                deployApp(app: 'checkout', env: 'prod', wait: true)
            }
        }
    }
}

// Credentials are stored centrally and bound to env vars at step time.
// Manage Jenkins → Credentials → System → Global credentials.

pipeline {
    agent any
    stages {
        stage('Docker login (username+password)') {
            steps {
                withCredentials([usernamePassword(
                        credentialsId: 'docker-hub',
                        usernameVariable: 'DOCKER_USER',
                        passwordVariable: 'DOCKER_PASS')]) {
                    sh 'echo $DOCKER_PASS | docker login -u $DOCKER_USER --password-stdin'
                }
            }
        }

        stage('API token (secret text)') {
            steps {
                withCredentials([string(credentialsId: 'gh-token', variable: 'GH_TOKEN')]) {
                    sh 'curl -H "Authorization: bearer $GH_TOKEN" https://api.github.com/user'
                }
            }
        }

        stage('Kubeconfig (secret file)') {
            steps {
                withCredentials([file(credentialsId: 'kube-prod', variable: 'KUBECONFIG')]) {
                    sh 'kubectl get pods -A'
                }
            }
        }

        stage('SSH key') {
            steps {
                withCredentials([sshUserPrivateKey(
                        credentialsId: 'deploy-key',
                        keyFileVariable: 'KEY_FILE',
                        usernameVariable: 'USER')]) {
                    sh 'ssh -i $KEY_FILE $USER@host "uptime"'
                }
            }
        }
    }
}
// Values are masked in the console log automatically.

// End-to-end Jenkinsfile: matrix tests → image build → manual approval → k8s deploy.
@Library('platform-shared@v1.4.0') _

pipeline {
    agent none

    options {
        timeout(time: 45, unit: 'MINUTES')
        buildDiscarder(logRotator(numToKeepStr: '30'))
        disableConcurrentBuilds()
        ansiColor('xterm')
    }

    parameters {
        choice(name: 'ENV', choices: ['stg', 'prod'])
    }

    stages {
        stage('Test matrix') {
            matrix {
                agent { label 'linux && docker' }
                axes {
                    axis { name 'NODE';    values '20', '22' }
                    axis { name 'BACKEND'; values 'postgres', 'mysql' }
                }
                stages {
                    stage('test') {
                        steps {
                            sh "docker compose -f compose.${BACKEND}.yml up -d"
                            sh "nvm exec ${NODE} npm test -- --ci --reporters=jest-junit"
                        }
                        post {
                            always { junit 'junit.xml' }
                            cleanup { sh 'docker compose down -v' }
                        }
                    }
                }
            }
        }

        stage('Build image') {
            agent { label 'linux && docker' }
            steps {
                withCredentials([usernamePassword(credentialsId: 'ghcr',
                                                  usernameVariable: 'U',
                                                  passwordVariable: 'P')]) {
                    sh 'echo $P | docker login ghcr.io -u $U --password-stdin'
                    sh "docker build -t ghcr.io/my-org/app:${BUILD_NUMBER} ."
                    sh "docker push  ghcr.io/my-org/app:${BUILD_NUMBER}"
                }
            }
        }

        stage('Deploy') {
            when { branch 'main' }
            steps {
                input message: "Deploy to ${params.ENV}?", ok: 'Go'
                deployApp(app: 'web', env: params.ENV)
            }
        }
    }

    post {
        failure { slackSend channel: '#ci-alerts', message: "FAILED: ${env.BUILD_URL}" }
        success { slackSend channel: '#deploys',   message: "✓ ${env.JOB_NAME} #${env.BUILD_NUMBER}" }
    }
}