Design Preflight, Post Actions, Timeouts and Recovery

Anil Jalela · Published Aug 12, 2026 · 4 min read

Pre steps prove that a build or deployment is safe to start. Post steps publish evidence, clean resources, notify operators and restore service after success or failure. Keep substantial logic in reviewed repository scripts while Jenkins defines ordering, credentials, conditions and evidence.

Map the lifecycle

Create a repository preflight script

#!/usr/bin/env bash
set -euo pipefail
: "${DEPLOY_ENV:?DEPLOY_ENV is required}"
: "${ARTIFACT:?ARTIFACT is required}"
case "$DEPLOY_ENV" in dev|staging|production) ;; *) echo 'invalid environment' >&2; exit 2;; esac
test -r "$ARTIFACT"
command -v sha256sum >/dev/null
command -v curl >/dev/null
sha256sum -c "${ARTIFACT}.sha256"
df -Pk . | awk 'NR==2 && $4 < 1048576 {exit 1}'

install -d -m 0755 ci
chmod 0755 ci/preflight.sh
git add ci/preflight.sh Jenkinsfile
git commit -m 'Add deployment preflight checks'

Use stage-level pre and post behavior

pipeline {
  agent { label 'deploy' }
  options {
    timestamps()
    timeout(time: 30, unit: 'MINUTES')
    disableConcurrentBuilds()
  }
  environment {
    DEPLOY_ENV = 'staging'
    ARTIFACT = "dist/app-${BUILD_NUMBER}.tgz"
  }
  stages {
    stage('Preflight') {
      steps { sh 'set -eu; ./ci/preflight.sh' }
    }
    stage('Deploy') {
      steps {
        retry(2) { sh 'set -eu; ./ci/deploy.sh' }
      }
      post {
        success { sh 'set -eu; ./ci/verify-deployment.sh' }
        failure { sh 'set +e; ./ci/collect-deploy-diagnostics.sh' }
      }
    }
  }
  post {
    always {
      junit testResults: 'reports/*.xml', allowEmptyResults: true
      archiveArtifacts artifacts: 'diagnostics/**', allowEmptyArchive: true
    }
    failure { echo "FAILED: ${env.JOB_NAME} #${env.BUILD_NUMBER}" }
    cleanup { deleteDir() }
  }
}

Retry only operations known to be idempotent or safely resumable. Retrying a partially applied database migration or payment action can multiply damage.

Understand Declarative post conditions

• always: reports and evidence needed for every result.
• success: acceptance checks and success-only publication.
• failure: diagnostics, rollback request and alert.
• unstable: test or quality result that did not fully pass.
• changed: notify when the result differs from the prior run.
• cleanup: final cleanup after other post conditions.

Use shell traps inside one script

#!/usr/bin/env bash
set -euo pipefail
tmp_dir="$(mktemp -d)"
cleanup() {
  rc=$?
  rm -rf -- "$tmp_dir"
  exit "$rc"
}
trap cleanup EXIT INT TERM
./ci/render-config.sh >"$tmp_dir/config"
./ci/apply.sh "$tmp_dir/config"

The trap preserves the action's exit status and cleans its own validated temporary directory. Jenkins post still handles cross-stage evidence and notifications.

Add a production approval

stage('Approve production') {
  when { branch 'main' }
  options { timeout(time: 30, unit: 'MINUTES') }
  input { message 'Promote the tested artifact to production?' }
  steps { echo 'Approval recorded by Jenkins' }
}

The approval must reference the already-tested artifact digest. Do not rebuild after approval.

Unsafe patterns

Unsafe: ./deploy.sh || true converts a failed deployment into a successful step. Use set +e only for best-effort diagnostics in a post-failure block, and retain the original build result.

Unsafe: placing secrets directly in Groovy-interpolated shell strings can expose them before masking. Bind credentials to environment variables and use a single-quoted shell script so the shell expands them at execution.

Troubleshoot post actions

stage('Deploy') {
  options { timeout(time: 15, unit: 'MINUTES') }
  steps {
    lock(resource: "deploy-${params.ENVIRONMENT}") {
      sh './ci/preflight.sh'
      sh './ci/deploy.sh'
      sh './ci/acceptance.sh'
    }
  }
  post {
    unsuccessful { sh './ci/collect-diagnostics.sh' }
    cleanup { deleteDir() }
  }
}

Official references

• Declarative Pipeline syntax
• Using a Jenkinsfile
• Pipeline basic steps