Declarative Pipeline Syntax, agent, stages, steps, options, parameters, environment, tools, and post: Diagnostics, Failure Modes, Security, and Performance

1. Diagnose the layer, not the symptom

Declarative Pipeline gives you an extra failure layer before ordinary Pipeline runtime: model validation. Preserve the failing source SHA and first error before changing anything. Then move down the lifecycle only as evidence demands.

flowchart TD
 A[Source SHA + Jenkinsfile] --> B{Declarative model valid?}
 B -->|no| C[Fix directive / scope only]
 B -->|yes| D[Queue + label + executor]
 D --> E[Agent / workspace / tools]
 E --> F[Pipeline step / shell / tests]
 F --> G[Credentials / network / external service]
 G --> H[Reports / artifacts / publication]
 H --> I[post conditions + final result]
 I --> J[Smallest safe retry / rerun]

2. Failure mode: directive in the wrong scope

Intentionally broken example:

pipeline {
  agent any
  stages {
    stage('Broken') {
      parameters {
        string(name: 'TARGET', defaultValue: 'sandbox')
      }
      steps { echo 'never reaches runtime' }
    }
  }
}

parameters belongs at the top level, so Declarative model validation should reject this structure. Preserve the validation message and Jenkinsfile SHA. Do not restart the agent, reinstall Git, or delete the workspace: none of those layers has been reached.

3. Failure mode: holding an expensive agent during approval

This shape acquires the stage's agent before it reaches the input step:

stage('Approve') {
  agent { label 'expensive-lab-agent' }
  steps {
    input message: 'Continue?'
    sh './bounded-action.sh'
  }
}

For long human waits, prefer a stage-level input directive so approval occurs before the agent is entered:

stage('Approve') {
  input { message 'Continue?' }
  agent { label 'expensive-lab-agent' }
  steps { sh './bounded-action.sh' }
}

Evidence is executor occupancy/queue behavior, not just elapsed wall time.

4. Failure mode: credentials exposed by interpolation/logging

Credentials Binding can mask recognized secret values, but masking cannot make careless command construction safe. Avoid Groovy interpolation of secrets into command strings, debug dumps of the environment, generated files with secrets, or tools that echo command-line arguments.

environment {
  LAB_TOKEN = credentials('ch10-fake-token')
}
stages {
  stage('Use secret safely') {
    agent { label 'lab-linux' }
    steps {
      sh '''
        set +x
        # The shell expands LAB_TOKEN; do not print it.
        test -n "$LAB_TOKEN"
        printf 'credential-present=yes\n'
      '''
    }
  }
}

The credential ID may be recorded as configuration evidence; the credential value must not be. Use only fake/disposable credentials in this lab.

5. Failure mode: post assumes a workspace that does not exist

With top-level agent none, a Pipeline-level post block has no guaranteed global workspace. Also, agent loss can make a previously used workspace unavailable. This is brittle:

pipeline {
  agent none
  stages {
    stage('Build') {
      agent { label 'lab-linux' }
      steps { sh 'echo ok > result.txt' }
    }
  }
  post {
    always {
      archiveArtifacts artifacts: 'result.txt'
    }
  }
}

Archive stage-owned evidence in a stage-level post or steps while that execution context exists, or explicitly allocate a node and transfer required data. Do not assume accidental workspace persistence.

6. Validation passed, but the stage never starts

A valid Declarative model can still wait forever because no online node matches the stage label, executors are saturated, or a cloud/ephemeral agent failed to provision. Preserve the queue reason. The correct evidence is the queue item, requested label, online nodes, and executor availability—not another syntax edit.

7. Tool resolution failure

If tools { maven 'maven-3.9' } is valid but the build fails resolving/installing the tool, inspect the Jenkins tool definition, plugin/provider involved, agent OS/architecture, filesystem permissions, and network requirements. Do not confuse the Java that runs Jenkins with the build JDK selected for a stage.

8. Performance: controller logic and executor occupancy

• Keep heavy computation/file/network work in agent-side tools rather than Groovy loops in script.
• Use agent none and stage agents when it meaningfully reduces idle executor time.
• Use stage-level input for long approvals before expensive allocation.
• Keep retries narrow so failures do not multiply resource use.
• Use sensible build-retention policy; evidence is valuable but unbounded retention consumes controller storage.

9. Evidence-first diagnostic sequence

1. Preserve job/build/queue IDs, source/Jenkinsfile SHA, and the first validation/runtime error.
2. Confirm Jenkins core, Java, Pipeline, Declarative, and relevant plugin baseline.
3. Confirm the Pipeline job configuration, trigger cause, parameters, and source revision.
4. Determine whether failure occurred during model validation, before any queue item.
5. If runtime started, inspect queue reason, requested label, node/executor, workspace, and tools.
6. Inspect Pipeline step/shell/test evidence.
7. Inspect credential binding, network, and external service only if the failure reached those layers.
8. Inspect reports/artifacts/publication separately from step success.
9. Apply the least destructive correction.
10. Retry/rerun only the smallest safe scope after checking external side effects.

10. Shortcuts that are not repairs

11. Minimal incident packet

Save the Jenkinsfile SHA, validation error or first stack/console failure, build URL/number, cause, non-secret parameters, queue item/reason, node/label/workspace, installed Pipeline/Declarative versions, tool versions, relevant archived evidence, and any externally verified target state. Record what you changed and the repairing source revision.

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current LTS line and tested Java configurations.
• Pipeline Syntax — authoritative Declarative sections/directives, scopes, options, parameters, environment, tools, when, input, and post.
• Using a Jenkinsfile — Pipeline-as-Code, environment, credentials, parameters, and source-controlled Jenkinsfiles.
• Jenkins Pipeline handbook — Pipeline concepts and execution model.
• Pipeline: Declarative — Declarative Pipeline implementation and current compatibility.
• Pipeline — Pipeline plugin aggregator baseline.
• Credentials Binding — credential-binding behavior and secret-handling cautions.
• Pipeline: Stage View — optional visualization; it is not the source of execution truth.