Jenkins中Matrix Axis构建独立工作区配置错误排查与修复

问题场景 #

尝试为Jenkins Matrix Axis构建配置独立工作区时，出现变量解析失败、Git克隆报错的问题，相关Jenkinsfile代码如下：

def job_name = env.JOB_NAME

pipeline {
    agent none
    stages {
        stage('Build') {
            matrix {
                agent {
                    node {
                        label 'BuildAndTest_Ubuntu1604' 
                        customWorkspace 'workspace/${job_name}/${BUILD}'
                    }
                }
                axes {
                    axis {
                        name 'BUILD'
                        values 'a', 'b', 'c', 'd', 'e', 'f'
                    }
                }
                when {
                    beforeAgent true
                    anyOf {
                        branch 'master'
                        branch 'develop'
                        branch pattern: '^release/.*', comparator: 'REGEXP'
                        equals expected: singleVariant, actual: env.BUILD
                        expression { return buildAllVariants }
                    }
                }
                stages {
                    stage('Build, Sign and Upload Bundle') {
                        steps {
                            script {
                                ...
                            }
                        }
                    }
                }
            }
        }
    }
}

错误现象 #

• customWorkspace中的${job_name}/${BUILD}未被正确解析，实际生成了名为${job_name}的字面量文件夹，以及额外的“project”命名空间文件夹
• Git克隆代码时失败，报错：

stderr: fatal: not a git repository (or any of the parent directories): .git

错误原因 #

1. 字符串引号类型错误：Jenkins Groovy语法中，单引号包裹的字符串是字面量字符串，不会解析其中的变量，导致${job_name}和${BUILD}直接被当作文件夹名称使用。
2. 变量作用域问题：在pipeline块外定义的job_name变量，无法在agent节点的上下文环境中被正确访问，因为agent块的执行时机早于脚本变量的初始化。

修复方案 #

修改customWorkspace的引号类型，并直接使用Jenkins内置环境变量，修复后的代码如下：

pipeline {
    agent none
    stages {
        stage('Build') {
            matrix {
                agent {
                    node {
                        label 'BuildAndTest_Ubuntu1604' 
                        // 使用双引号解析变量，直接调用env内置变量
                        customWorkspace "workspace/${env.JOB_NAME}/${env.BUILD}"
                    }
                }
                axes {
                    axis {
                        name 'BUILD'
                        values 'a', 'b', 'c', 'd', 'e', 'f'
                    }
                }
                when {
                    beforeAgent true
                    anyOf {
                        branch 'master'
                        branch 'develop'
                        branch pattern: '^release/.*', comparator: 'REGEXP'
                        equals expected: singleVariant, actual: env.BUILD
                        expression { return buildAllVariants }
                    }
                }
                stages {
                    stage('Build, Sign and Upload Bundle') {
                        steps {
                            script {
                                ...
                            }
                        }
                    }
                }
            }
        }
    }
}

额外优化建议 #

• 建议使用绝对路径定义工作区，避免相对路径带来的歧义，例如：

  customWorkspace "/var/lib/jenkins/workspace/${env.JOB_NAME}/${env.BUILD}"
  

• 如果需要确保工作区路径唯一，可以结合env.BUILD_NUMBER等更多环境变量生成路径。

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