Top-level vs stage-level environment for DEPLOY_TARGET consistency in steps and post

Short answer

A stage post block resolves environment variables from the stage scope. If the stage defines its own environment entry for DEPLOY_TARGET, both the stage's steps and its post actions see that value. If the stage has no override, both fall back to the top-level value. So within a single stage, steps and post are consistent — you do not get a mix of the two scopes.

Likely explanation vs. confirmed facts

Confirmed by long-standing Declarative Pipeline behavior:

• The top-level environment block is a pipeline-wide default.
• A stage-level environment block shadows the top-level entry of the same name for everything inside that stage, including post conditions (always, failure, success).
• Resolution happens when the code runs, not at stage start. A post action reads the variable at the moment it executes.

The part that is version-sensitive and should be verified on your installation: this scoping is implemented by the Pipeline Model Definition plugin (with workflow-cps / workflow-basic-steps), not Jenkins core. Edge cases — especially around parallel and matrix stages — have had bug fixes across plugin releases, so an older LTS plugin set may not match current documentation.

Recommended pattern for your case

Yes — define DEPLOY_TARGET explicitly at stage level in any stage whose cleanup, notification, or archiving logic depends on it:

pipeline {
  agent any
  environment {
    DEPLOY_TARGET = 'staging'   // pipeline-wide default
  }
  stages {
    stage('Deploy Prod') {
      environment {
        DEPLOY_TARGET = 'prod'  // shadows the default for this stage
      }
      steps {
        sh 'echo deploying to $DEPLOY_TARGET'
      }
      post {
        failure {
          sh 'echo rollback for $DEPLOY_TARGET'
        }
        always {
          archiveArtifacts artifacts: "reports/${env.DEPLOY_TARGET}/**", allowEmptyArchive: true
        }
      }
    }
  }
}

This keeps the override declarative and local. Steps and post in that stage both see prod; every other stage sees staging.

One real risk: imperative mutation

Avoid env.DEPLOY_TARGET = 'x' inside steps. That mutates the run's environment globally and can leak into later stages' post blocks, which is exactly the inconsistency you are trying to prevent. Declarative environment blocks are scoped; imperative assignment is not.

Verify on your version

Because behavior is plugin-version dependent, run a minimal test:

1. Create a Jenkinsfile with top-level DEPLOY_TARGET = 'a' and one stage with environment { DEPLOY_TARGET = 'b' } whose steps and post { always { echo env.DEPLOY_TARGET } } both echo the value. Both should print b.
2. Add a second stage with no override; its steps and post should both print a.
3. Note the installed versions under Manage Jenkins > Plugins (Pipeline: Model API / Declarative) and re-run after upgrades.

If your test shows the post block printing the top-level value while steps print the override, report the plugin versions — that would indicate a version-specific bug rather than intended behavior.