Jenkins

---
name: jenkins
description: "Covers Jenkins CI/CD: Declarative and Scripted Pipelines, Jenkinsfile, plugins, shared libraries, agents, Blue Ocean, security, and Jenkins administration. WHEN: \"Jenkins\", \"Jenkinsfile\", \"Jenkins pipeline\", \"Jenkins plugin\", \"shared library\", \"Jenkins agent\", \"Jenkins node\", \"Blue Ocean\", \"Jenkins X\", \"Jenkins security\", \"Jenkins admin\"."
license: MIT
---

# Jenkins Expert

This skill covers Jenkins, the most widely deployed CI/CD automation server. Jenkins is self-hosted, open source, and extensible through 1800+ plugins. Pipeline configuration is via Jenkinsfile (Groovy DSL) stored in the repository. Current LTS is 2.541+.

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Load `references/diagnostics.md` for pipeline failures, plugin issues, agent connectivity, and performance problems
   - **Architecture** -- Load `references/architecture.md` for controller/agent model, plugin system, pipeline engine, and distributed builds
   - **Best practices** -- Load `references/best-practices.md` for pipeline design, security hardening, shared libraries, and administration

2. **Load context** -- Read the relevant reference file.

3. **Analyze** -- Apply Jenkins-specific reasoning. Consider Declarative vs Scripted Pipeline, plugin ecosystem, agent labels.

4. **Recommend** -- Provide Jenkinsfile examples with explanations.

5. **Verify** -- Suggest validation (Replay, Pipeline Syntax generator, Blue Ocean visualization).

## Core Concepts

### Declarative Pipeline

```groovy
// Jenkinsfile (Declarative)
pipeline {
    agent {
        docker {
            image 'node:22'
            args '-v /tmp:/tmp'
        }
    }

    environment {
        CI = 'true'
        DEPLOY_CREDS = credentials('deploy-credentials')
    }

    options {
        timeout(time: 30, unit: 'MINUTES')
        retry(2)
        timestamps()
        buildDiscarder(logRotator(numToKeepStr: '10'))
    }

    triggers {
        pollSCM('H/5 * * * *')
    }

    stages {
        stage('Build') {
            steps {
                sh 'npm ci'
                sh 'npm run build'
            }
        }

        stage('Test') {
            parallel {
                stage('Unit Tests') {
                    steps {
                        sh 'npm run test:unit'
                    }
                }
                stage('Integration Tests') {
                    steps {
                        sh 'npm run test:integration'
                    }
                }
            }
        }

        stage('Deploy') {
            when {
                branch 'main'
            }
            input {
                message 'Deploy to production?'
                ok 'Deploy'
            }
            steps {
                sh './deploy.sh'
            }
        }
    }

    post {
        always {
            junit '**/test-results/*.xml'
            archiveArtifacts artifacts: 'dist/**', fingerprint: true
        }
        failure {
            mail to: 'team@example.com',
                 subject: "Failed: ${currentBuild.fullDisplayName}",
                 body: "Build failed: ${env.BUILD_URL}"
        }
        cleanup {
            cleanWs()
        }
    }
}
```

### Scripted Pipeline

```groovy
// Jenkinsfile (Scripted) — full Groovy flexibility
node('linux') {
    try {
        stage('Checkout') {
            checkout scm
        }

        stage('Build') {
            def nodeHome = tool name: 'Node-22', type: 'jenkins.plugins.nodejs.tools.NodeJSInstallation'
            env.PATH = "${nodeHome}/bin:${env.PATH}"
            sh 'npm ci && npm run build'
        }

        stage('Test') {
            parallel(
                'Unit': { sh 'npm run test:unit' },
                'E2E':  { sh 'npm run test:e2e' }
            )
        }

        stage('Deploy') {
            if (env.BRANCH_NAME == 'main') {
                input 'Deploy to production?'
                sh './deploy.sh'
            }
        }

    } catch (e) {
        currentBuild.result = 'FAILURE'
        throw e
    } finally {
        junit '**/test-results/*.xml'
        cleanWs()
    }
}
```

### Declarative vs Scripted

| Aspect | Declarative | Scripted |
|---|---|---|
| **Syntax** | Structured, opinionated | Free-form Groovy |
| **Learning curve** | Lower | Higher (need Groovy knowledge) |
| **Flexibility** | Limited (can use `script {}` blocks) | Unlimited |
| **Validation** | Validated before execution | Fails at runtime |
| **Restart** | Stage-level restart (CloudBees) | Not supported |
| **Recommendation** | Default choice for new pipelines | When Declarative is too restrictive |

## Agent Configuration

### Agent Types

```groovy
// Run on any available agent
agent any

// Run on agent with specific label
agent { label 'linux && docker' }

// Run in a Docker container
agent {
    docker {
        image 'maven:3.9-eclipse-temurin-21'
        label 'docker-capable'
        args '-v $HOME/.m2:/root/.m2'
    }
}

// Run in a Kubernetes pod
agent {
    kubernetes {
        yaml '''
        apiVersion: v1
        kind: Pod
        spec:
          containers:
          - name: maven
            image: maven:3.9
            command: ['sleep', '99d']
          - name: docker
            image: docker:latest
            command: ['sleep', '99d']
        '''
    }
}

// No agent (stage-level allocation)
agent none
```

### Agent Labels

Labels organize agents by capability:

| Label | Meaning |
|---|---|
| `linux` | Linux OS |
| `windows` | Windows OS |
| `docker` | Docker available |
| `gpu` | GPU available |
| `large` | High-resource node |
| `zone-a` | Specific network zone |

## Shared Libraries

Shared libraries provide reusable Groovy code across pipelines:

```
shared-library/
├── vars/
│   ├── buildApp.groovy       # Global variable (callable as buildApp())
│   └── deployApp.groovy      # Global variable
├── src/
│   └── com/myorg/
│       └── Pipeline.groovy   # Class library
└── resources/
    └── templates/            # Non-Groovy files
```

```groovy
// vars/buildApp.groovy
def call(Map config = [:]) {
    pipeline {
        agent { label config.agent ?: 'linux' }
        stages {
            stage('Build') {
                steps {
                    sh "${config.buildCommand ?: 'make build'}"
                }
            }
            stage('Test') {
                steps {
                    sh "${config.testCommand ?: 'make test'}"
                }
            }
        }
    }
}
```

```groovy
// Consumer Jenkinsfile
@Library('my-shared-library@main') _

buildApp(
    agent: 'docker',
    buildCommand: 'npm run build',
    testCommand: 'npm test'
)
```

## Credentials Management

```groovy
// Username/password
withCredentials([usernamePassword(
    credentialsId: 'dockerhub',
    usernameVariable: 'DOCKER_USER',
    passwordVariable: 'DOCKER_PASS'
)]) {
    sh 'docker login -u $DOCKER_USER -p $DOCKER_PASS'
}

// SSH key
withCredentials([sshUserPrivateKey(
    credentialsId: 'deploy-key',
    keyFileVariable: 'SSH_KEY'
)]) {
    sh 'ssh -i $SSH_KEY user@server deploy.sh'
}

// Secret text
withCredentials([string(
    credentialsId: 'api-token',
    variable: 'API_TOKEN'
)]) {
    sh 'curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com'
}

// Secret file
withCredentials([file(
    credentialsId: 'kubeconfig',
    variable: 'KUBECONFIG'
)]) {
    sh 'kubectl get pods'
}
```

## Key Plugins

| Plugin | Purpose |
|---|---|
| **Pipeline** | Jenkinsfile support (Declarative + Scripted) |
| **Git** | Git SCM integration |
| **Docker Pipeline** | Docker agent and build support |
| **Kubernetes** | K8s pod-based agents |
| **Credentials Binding** | Inject credentials into builds |
| **Blue Ocean** | Modern pipeline visualization UI |
| **Pipeline Utility Steps** | readJSON, writeJSON, readYaml, zip/unzip |
| **Warnings Next Generation** | Static analysis result aggregation |
| **JUnit** | Test result reporting |
| **Timestamper** | Add timestamps to console output |
| **Build Discarder** | Automatic old build cleanup |
| **Role Strategy** | Fine-grained RBAC |
| **Matrix Authorization** | Per-project permissions |
| **OWASP Dependency-Check** | Dependency vulnerability scanning |

## Reference Files

- `references/architecture.md` — Controller/agent model, plugin system, pipeline engine, distributed builds, HA configurations
- `references/best-practices.md` — Pipeline design, security hardening, shared library patterns, administration, backup/restore, upgrade strategy
- `references/diagnostics.md` — Pipeline debugging, plugin conflicts, agent connectivity, performance issues, Groovy sandbox errors