Opscraft
Jenkinsfile · Lesson 4 of 10 · 5 min read

Conditions, parallelism and resilience

when

when { branch 'main' }                                  // multibranch branch name (glob ok: 'release/*')
when { tag pattern: 'v\\d+\\.\\d+\\.\\d+', comparator: 'REGEXP' }
when { buildingTag() }
when { changeRequest() }                                // pull request builds
when { changeRequest target: 'main' }
when { changeset 'services/orders/**' }                 // files changed in this build
when { environment name: 'DEPLOY', value: 'true' }
when { expression { params.RUN_E2E && env.BRANCH_NAME != 'experimental' } }
when { triggeredBy 'TimerTrigger' }                     // only on cron runs
when { allOf { branch 'main'; not { changeRequest() } } }
when { anyOf { branch 'main'; branch 'release/*' } }

Evaluation order modifiers:

  • beforeAgent true — evaluate the condition before allocating the stage's agent (don't spin up a pod just to skip the stage).
  • beforeInput true — evaluate before showing the input prompt.
  • beforeOptions true — evaluate before applying stage options (like timeouts).
Enlarge diagramrunsrunsrunsskippedrunsrunsskippedrunsskippedskippedskippedrunsPR buildmaintag v1.4.0Build + testImage pushDeploy stagingDeploy prod
Figure 1. when decides whether a stage runs at all. A typical multibranch pipeline uses it to keep deploys to main and tags.
Swipe sideways to see all of it, or tap to open it full screen.

parallel

stage('Checks') {
  failFast true                                  // abort sibling branches if one fails
  parallel {
    stage('Unit')        { steps { sh 'mvn -B test' } }
    stage('Lint')        { steps { sh 'mvn -B checkstyle:check' } }
    stage('Dependency scan') { steps { sh 'trivy fs --exit-code 1 --severity CRITICAL .' } }
  }
}

Parallel branches each can have their own agent. Without failFast, all branches run to completion and the stage fails at the end.

Enlarge diagramBuildUnitLintSASTfailsDependency scanaborted by failFastImageskipped
Figure 2. parallel runs independent checks at the same time; failFast stops the others when one fails.
Swipe sideways to see all of it, or tap to open it full screen.

matrix

Run the same stages across combinations of axes:

stage('Test matrix') {
  matrix {
    axes {
      axis { name 'JDK';      values '17', '21' }
      axis { name 'DATABASE'; values 'postgres', 'mysql' }
    }
    excludes {
      exclude {
        axis { name 'JDK'; values '17' }
        axis { name 'DATABASE'; values 'mysql' }
      }
    }
    agent { kubernetes { yaml podFor(JDK) } }     // podFor: helper defined in your shared library
    stages {
      stage('Test') { steps { sh "./gradlew test -Pdb=${DATABASE}" } }
    }
  }
}

Resilience steps

retry(3) { sh './flaky-integration-call.sh' }             // retry a block
retry(count: 3, conditions: [agent(), kubernetesAgent()]) { ... }   // retry only if the agent/pod died
timeout(time: 10, unit: 'MINUTES') { sh './e2e.sh' }       // bound a step
waitUntil(initialRecurrencePeriod: 5000) {                 // poll until true
  sh(script: 'curl -fs https://staging/health', returnStatus: true) == 0
}
catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') { sh './optional-check.sh' }   // stage yellow, build continues
warnError('Coverage check failed') { sh './coverage-gate.sh' }     // mark unstable, continue
unstable('Message')                                         // mark unstable explicitly
error('Message')                                            // fail now
lock(resource: 'staging-env') { sh './deploy.sh staging' }  // Lockable Resources: one deploy at a time
milestone(1)                                                // older builds can't pass a milestone a newer build passed

Retrying flaky tests hides problems — use it briefly while you fix the cause, and track flakiness.

Enlarge diagramretry(3)flaky network calltimeoutbound a stepwaitUntilpoll until healthycatchErrorstage yellow, build goes onlockone deploy to staging at a timemilestoneolder build cannot overtake newer
Figure 3. Resilience steps and what each is for.
Swipe sideways to see all of it, or tap to open it full screen.