Declarative Pipeline agent directive scope limits

Workspace Persistence and Agent Transitions

p>Jenkins does not maintain a consistent workspace when transitioning between a global agent and a stage-specific agent. When a stage-level agent directive overrides the global definition, Jenkins allocates a new executor, which may reside on a different physical or virtual node. This results in the creation of a fresh, empty workspace for that specific stage.

How Jenkins Handles Workspace Cleanup

The workspace lifecycle is tied to the specific executor and node. When a pipeline moves from a global agent to a stage-specific agent:

• The global agent's executor is released, and its workspace remains on that node (but is inaccessible to the next stage).
• The stage-specific agent initializes a new workspace on its assigned node.
• Files from the global workspace are not copied or synchronized to the new stage workspace unless explicitly moved via plugins or mechanisms.

Maintaining Data Across Agent Types

There is no documented automated method to maintain a consistent workspace across different agent types within a single execution. To pass data between agents, you must use one of the following strategies:

1. Stash and Unstash: Use the stash to save files to the Jenkins controller and unstash to retrieve them in a subsequent stage. This is the standard approach for small-to-medium files.
2. Archives: Use archiveArtifacts to persist files in the build history and copyArtifacts to pull them later.
3. Shared Storage: Mount a shared network file system (e.g., NFS) across all agents. This allows direct file access but introduces complexities regarding file locking and performance.

Example Implementation

pipeline {
    agent { label 'linux-node' }
    stage('Build') {
        steps {
            sh 'echo "build data" > output.txt'
            stash name: 'data', includes: 'output.txt'
        }
    }
    stage('Test') {
        agent { label 'windows-node' }
        steps {
            unstash name: 'data'
            bat 'type output.txt'
        }
    }
}