Overview
Jenkins Declarative Pipeline (introduced 2017) is the modern Jenkinsfile syntax - replaces older Scripted Pipeline for most use cases.
A Jenkinsfile defines:
When to use
For new projects in 2026+: GitHub Actions / GitLab CI offer better managed-runner experiences. Jenkins shines in self-hosted
How to use
Step 1 - Basic Jenkinsfile
// Jenkinsfile
pipeline {
agent any
stages {
stage('Build') {
steps {
sh 'npm ci'
}
}
stage('Test') {
steps {
sh 'npm test'
}
}
}
}agent any runs on any available executor; pin via agent { label 'linux' } or agent { docker { image 'node:22' } }.
Step 2 - Docker agent
pipeline {
agent {
docker {
image 'node:22'
args '-v /tmp:/tmp'
}
}
stages {
stage('Test') {
steps {
sh 'npm ci && npm test'
}
}
}
}Docker agents provide reproducibility - same Node version on every run.
Advanced pipeline patterns
Deeper stage recipes are split into reference files:
When to retry
stage('Test') {
steps {
retry(2) {
sh 'npm test'
}
}
}Use sparingly - retries hide flake. Prefer flaky-test-quarantine (in the qa-flake-triage plugin).
Worked example
A regulated team runs its suite on a self-hosted Jenkins with a shared integration database.
Result: reproducible runs, no DB contention across parallel builds, and test reports plus notifications on every outcome.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Scripted pipeline for new code | Declarative is the standard; better tooling support. | Declarative Pipeline (Step 1). |
Plaintext credentials in Jenkinsfile | Secret leak. | withCredentials({...}) (environment-and-triggers). |
No post { always {} } for artifact upload | Failure investigation incomplete. | Always upload (post-actions). |
| Single-agent pipeline for parallel work | No parallelism; slow. | Parallel stages (parallel-and-matrix). |
Missing timeout | Hung jobs consume executors indefinitely. | options { timeout(...) } (environment-and-triggers). |
Skipping agent { docker {...}} | Inconsistent runtime per agent; hard to reproduce. | Docker agents (Step 2). |
Limitations
References
Jenkins - environment, credentials, resource locks, and triggers
View source (opens in a new tab) (opens in new window)Deeper recipes split out of jenkinsfile-test-stages SKILL.md: serializing shared infrastructure, injecting environment plus masked credentials, and scheduling / multi-branch behavior.
Lockable resources
pipeline {
agent any
stages {
stage('Integration') {
steps {
lock(resource: 'shared-test-database') {
sh 'npm run test:integration'
}
}
}
}
}lock(...) uses the Lockable Resources Plugin to serialize access to shared resources (test DB, license-locked tool, etc.).
Environment + credentials
pipeline {
agent any
environment {
CI = 'true'
NODE_ENV = 'test'
}
stages {
stage('Test') {
steps {
withCredentials([string(credentialsId: 'npm-auth-token', variable: 'NODE_AUTH_TOKEN')]) {
sh 'npm ci && npm test'
}
}
}
}
}withCredentials([...]) masks secrets in build logs.
Multi-branch + scheduled
pipeline {
agent any
triggers {
cron('0 4 * * *') // daily at 4 AM
pollSCM('*/15 * * * *') // poll every 15 min (or use webhook)
}
options {
timeout(time: 30, unit: 'MINUTES')
timestamps()
ansiColor('xterm')
buildDiscarder(logRotator(numToKeepStr: '20'))
}
stages { /* ... */ }
}Per-branch behavior via Multibranch Pipeline job type (separate config in Jenkins UI).
Deeper recipes split out of jenkinsfile-test-stages SKILL.md: running stages concurrently, and fanning a stage across an OS × runtime matrix.
Parallel stages
pipeline {
agent any
stages {
stage('Tests') {
parallel {
stage('Unit') {
steps { sh 'npm test' }
}
stage('Integration') {
steps { sh 'npm run test:integration' }
}
stage('E2E') {
agent {
docker { image 'mcr.microsoft.com/playwright:v1.50.0-noble' }
}
steps { sh 'npx playwright test' }
}
}
}
}
}Parallel stages can have different agents - useful when E2E needs a Playwright-equipped image.
Matrix builds (Jenkins 2.302+)
pipeline {
agent none
stages {
stage('Test matrix') {
matrix {
axes {
axis {
name 'OS'
values 'linux', 'macos', 'windows'
}
axis {
name 'NODE_VERSION'
values '20', '22'
}
}
stages {
stage('Test') {
agent { label "${OS}" }
steps {
sh 'npm ci && npm test'
}
}
}
}
}
}
}Matrix runs all OS × Node combinations in parallel.
Deeper recipe split out of jenkinsfile-test-stages SKILL.md: the post {} block that runs after stages - JUnit publishing, artifact archiving, and outcome-specific notifications.
Post actions
pipeline {
agent any
stages {
stage('Test') {
steps {
sh 'npm test'
}
}
}
post {
always {
// Always run - even on failure
junit 'reports/junit/*.xml'
archiveArtifacts artifacts: 'coverage/**', allowEmptyArchive: true
}
success {
slackSend(channel: '#ci', message: "✅ Build ${env.BUILD_NUMBER} passed")
}
failure {
slackSend(channel: '#ci', message: "❌ Build ${env.BUILD_NUMBER} failed: ${env.BUILD_URL}")
}
unstable {
// E.g., tests passed but with warnings
mail to: 'team@example.com', subject: "Build ${env.BUILD_NUMBER} unstable"
}
}
}post { always {} } runs on any outcome - essential for artifact upload + notifications.
The junit '...' step (from JUnit Plugin) parses XML and renders results in Jenkins UI.