Jenkins Pipeline工作区路径确定规则及@2后缀异常问题咨询

Let's break down your questions one by one based on Jenkins LTS 2.107.2 and the Pipeline plugin behavior:

1. How is the workspace path determined, and why did the @2 suffix suddenly appear? #

Jenkins uses the DefaultWorkspaceLocatorStrategy by default to assign workspace paths. Under normal circumstances, for a job named jobname, the default workspace path is:

$JENKINS_HOME/workspace/jobname

The @n suffix gets added when Jenkins detects that the default workspace path is "occupied"—this could stem from:

• A leftover .lock file in the default workspace directory from a previous build that didn’t clean up properly (even if the build finished successfully).
• An inconsistency in how Jenkins tracks executor-workspace associations. In your case, when the job ran on executor 2 and reused the default workspace, Jenkins might have marked that workspace as linked to executor 2. Later, when the job tried to run on executor 1, Jenkins thought the default path was still tied to executor 2 (and thus "occupied"), so it created a new workspace with @2 (a tracking glitch led it to pick this suffix instead of @1).

Even after you set the executor count to 1 and deleted the workspace, Jenkins might have retained cached metadata about the workspace association, causing it to keep using the @2 path.

2. Does Jenkins reuse workspaces across executors? #

By default, Jenkins does not intentionally reuse workspaces across executors when a job is configured to disallow concurrent builds. The expected behavior is that a non-concurrent job will use a single workspace tied to whichever executor it’s running on at the time.

That said, edge cases can cause cross-executor reuse:

• If a previous build on another executor didn’t properly release the workspace lock, Jenkins might let a new build on a different executor reuse that workspace (since it doesn’t detect the lock as active).
• Metadata glitches in Jenkins’ node/workspace tracking can lead it to associate a job with a workspace originally used by another executor—exactly what you experienced.

3. Where is the reuse-related information stored? #

This metadata isn’t stored in the job’s configuration—it lives in Jenkins’ backend storage and node-specific files:

• Node workspace records: For each agent node, Jenkins stores workspace associations in $JENKINS_HOME/nodes/<node-name>/workspaces/. This directory contains symbolic links or marker files mapping jobs to their assigned workspaces on that node.
• Workspace lock files: When a build runs, Jenkins creates a .lock file in the workspace directory. If this file isn’t deleted (e.g., due to a sudden build abort or agent crash), Jenkins will treat the workspace as occupied.
• Jenkins internal metadata: Jenkins stores workspace assignment details in its internal XML files or embedded database—you can find build-specific records in $JENKINS_HOME/jobs/<job-name>/builds/, and global/node configurations in $JENKINS_HOME/config.xml.

To fix your persistent @2 workspace issue, you could try these steps:

1. Stop the Jenkins service.
2. Delete the workspace records for your job in $JENKINS_HOME/nodes/<your-node>/workspaces/.
3. Ensure all leftover .lock files and old workspace directories are removed from the agent.
4. Restart Jenkins.

内容的提问来源于stack exchange，提问作者ami