Mechanisms and Practices for Passing Variables Between Stages in Jenkins Declarative Pipelines

In Jenkins declarative pipelines, passing variables between stages is a critical requirement for implementing complex build logic. Unlike scripted pipelines, declarative pipelines impose more structured syntactic constraints, requiring developers to adopt specific patterns for managing variable scope. This article systematically analyzes solutions to this technical challenge based on community best practices.

Variable Scope and Declaration Mechanisms

Stages in declarative pipelines have isolated execution environments by default, meaning variables defined in one stage are not directly accessible in others. To overcome this limitation, it is essential to understand Jenkins pipeline variable scoping rules. The core solution involves defining Groovy variables outside the pipeline block, making them globally accessible objects.

def myVar = 'initial_value'

pipeline {
  agent any
  stages {
    stage('one') {
      steps {
        echo "Current value: ${myVar}"
      }
    }
  }
}

As shown in the code above, the myVar variable defined outside the pipeline block can be read in all stages. This declaration approach establishes the foundation for cross-stage data sharing.

Dynamic Assignment and File Reading

In actual build processes, variable values often need to be dynamically generated through shell commands or file operations. Declarative pipelines require such operations to be executed within script blocks to bypass the constraints of declarative syntax.

stage('Data Generation') {
  steps {
    sh 'echo generated_value > output.txt'
    script {
      myVar = readFile('output.txt').trim()
    }
    echo "Updated: ${myVar}"
  }
}

The readFile method reads file content, while the trim() method removes leading and trailing whitespace, ensuring clean string values. This approach is particularly suitable for scenarios requiring data capture from external command outputs.

Complete Workflow Example

Combining the above techniques, the following example demonstrates a complete workflow for cross-stage variable passing:

def buildVersion = ''

pipeline {
  agent { label 'linux' }
  stages {
    stage('Version Detection') {
      steps {
        sh 'git describe --tags > version.txt'
        script {
          buildVersion = readFile('version.txt').trim()
        }
        echo "Detected version: ${buildVersion}"
      }
    }
    
    stage('Conditional Build') {
      when {
        expression { buildVersion.startsWith('v') }
      }
      steps {
        echo "Executing tagged build: ${buildVersion}"
        build job: 'release_pipeline', 
          parameters: [string(name: 'VERSION', value: buildVersion)]
      }
    }
    
    stage('Fallback Process') {
      when {
        expression { !buildVersion.startsWith('v') }
      }
      steps {
        echo "Executing development build: ${buildVersion}"
      }
    }
  }
}

In this example, the first stage retrieves version information via a Git command and stores it in the buildVersion variable. Subsequent stages perform conditional checks based on this variable's value to decide whether to trigger downstream build jobs. This illustrates the critical role of variable passing in implementing intelligent pipeline workflows.

Limitations of Environment Variable Approach

Another common method involves using the env global variable for data passing:

stage('Set Environment Variable') {
  steps {
    script {
      env.CUSTOM_VAR = sh(script: 'echo dynamic_value', returnStdout: true).trim()
    }
  }
}

stage('Use Environment Variable') {
  steps {
    echo "${env.CUSTOM_VAR}"
  }
}

While this approach works, note that environment variables are mutable across all stages, potentially leading to unintended side effects. In contrast, using Groovy variables provides more precise scope control.

Best Practices Summary

Based on technical analysis and practical validation, we summarize the following best practices:

1. Prefer Groovy Variables: Define variables outside the pipeline block and perform assignments within script blocks to ensure type safety and clear scope.
2. Choose Data Sources Appropriately: For simple values, use direct shell command outputs; for complex data or file contents, employ the readFile method.
3. Handle Strings Carefully: Use the trim() method to clean data, avoiding logic errors caused by hidden whitespace characters.
4. Combine with Conditional Execution: Utilize when directives and variable values to enable dynamic stage execution, enhancing pipeline flexibility.
5. Avoid Overusing Environment Variables: Environment variables are suitable for configuration information but not for frequently modified build state data.

By adhering to these principles, developers can build robust pipeline systems that comply with declarative pipeline standards while implementing complex logic. Passing variables between stages is no longer a technical obstacle but a powerful tool for achieving advanced continuous integration/continuous deployment functionalities.