Pipeline Steps, Error Handling, retry, timeout, catchError, input, waitUntil, and Resilient Flow Control: Configuration, Design Choices, and Tradeoffs

1. Retry versus fail fast

Retry is appropriate for transient failures when the body is safe to repeat and a later attempt can reasonably succeed. Fail fast when the input is invalid, a policy gate failed deterministically, a required artifact is missing, or the operation may already have caused an external side effect that Jenkins cannot verify.

2. catchError versus try/catch/finally

catchError is concise when the desired outcome is “continue, but mark the stage/build non-green.” Plain Groovy try/catch/finally is clearer when you need explicit compensation, selective exception handling, or to rethrow after collecting evidence.

try {
  sh './required-check.sh'
} catch (err) {
  writeFile file: 'evidence/required-check-failed.txt', text: "${err.class.name}\n"
  throw err
} finally {
  echo 'Evidence collection finished'
}

Do not catch broadly and forget to rethrow a critical failure. Also avoid swallowing user aborts or timeouts unless the behavior is intentionally documented.

3. Timeout placement changes what is bounded

4. Input inside versus outside an agent

Human approval usually belongs before agent allocation: the decision can take minutes or hours, while an executor is scarce capacity. Keep approval inside a node only when the very same allocated workspace/process must remain intact and you consciously accept the occupancy cost. Prefer persisting required evidence first, releasing the node, then reacquiring deterministic inputs after approval.

5. waitUntil versus event-driven integration

Polling is straightforward for a lab or a system with no callback mechanism. It costs controller scheduling activity and can amplify load if many runs poll aggressively. waitUntil backs off its recurrence interval, but event-driven webhooks/callbacks or an external orchestrator may scale better for long waits. Regardless of strategy, define a deadline and retain the observed target state.

6. Rerun is a new attempt, not time travel

A rerun occurs in a changed world: credentials may rotate, targets may already contain the release, dependencies may disappear, and previous workspace files may be gone. Record immutable source/artifact IDs and inspect external state before repeating side effects. A replay of Pipeline logic does not automatically reproduce the external preconditions of the earlier run.

7. Worked design: maintenance simulation

Requirement: validate a target, wait for approval, execute one local synthetic mutation, then verify it. Choose:

8. Cost, performance, and maintainability

Retries consume agent time and can amplify downstream load. Human waits inside nodes waste executors. Tight polling increases controller and service pressure. Overuse of catchError creates ambiguous “successful” pipelines. Optimize for truthful state first, then capacity: small bounded retries, sparse polling, released agents during waits, and explicit build/stage results.

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current LTS and tested Java configurations.
• Pipeline: Basic Steps — current retry, timeout, catchError, waitUntil, sleep, and related step contracts.
• Pipeline: Input Step reference — input, submitter restrictions, identifiers, and captured approver identity.
• Pipeline: Basic Steps plugin — current plugin baseline and dependencies.
• Pipeline: Input Step plugin — current plugin baseline and security history.
• Jenkins Pipeline handbook — durable Pipeline execution and Jenkinsfile concepts.
• Pipeline Best Practices — controller/agent boundaries and safe Pipeline design.