Jenkins自定义库步骤未用script块包裹时执行失败求助

I'm facing a confusing issue with a custom Jenkins step I wrote to simplify cloning GitHub/Bitbucket repos. The step has methods to handle branches and PRs via checkout(), and it works perfectly when called inside script { gitUtils.cloneRepo(...) }. But when I try to use it directly in a declarative pipeline without wrapping it in script{}, I get these errors:

WorkflowScript: 25: Expected a symbol @ line 25, column 17.
   gitUtils().getCredentials(repo)
   ^
WorkflowScript: 26: Expected a symbol @ line 26, column 17.
   gitUtils().cloneRepo(url: repo)
   ^
WorkflowScript: 27: Expected a symbol @ line 27, column 17.
   gitUtils().getRevision()
   ^
WorkflowScript: 26: Invalid parameter "url", did you mean "message"? @ line 26, column 38.
   gitUtils().cloneRepo(url: repo)
   ^
WorkflowScript: 27: Missing required parameter: "message" @ line 27, column 17.
   gitUtils().getRevision()

Here's the code for my custom step:

import java.lang.IllegalArgumentException

def call() {
    return this
}

def cloneRepo(Map parameters = [url: null, branch: "master", credentials: null]) {
    def url = parameters.getOrDefault("url", null)
    def branch = parameters.getOrDefault("branch", "master")
    def credentials = parameters.getOrDefault("credentials", null)

    script {
        if(!url) {
            throw new IllegalArgumentException("cloneRepo() expects url argument to be present!")
        }
        if(credentials == null) {
            credentials = getCredentials(url)
        }
        if (branch.matches("\\d+") || branch.matches("PR-\\d+")) {
            if (branch.matches("PR-\\d+")) {
                branch = branch.substring(3)
            }
            checkout changelog: false, poll: false, scm: [
                $class: 'GitSCM',
                branches: [[name: 'pr/' + branch]],
                doGenerateSubmoduleConfigurations: false,
                extensions: [[$class: 'LocalBranch', localBranch: 'pr/' + branch]],
                submoduleCfg: [],
                userRemoteConfigs: [[
                    credentialsId: credentials,
                    refspec: 'refs/pull/' + branch + '/head:pr/' + branch,
                    url: url
                ]]
            ]
        } else {
            checkout changelog: false, poll: false, scm: [
                $class: 'GitSCM',
                branches: [[name: branch]],
                doGenerateSubmoduleConfigurations: false,
                extensions: [],
                submoduleCfg: [],
                userRemoteConfigs: [[
                    credentialsId: credentials,
                    url: url
                ]]
            ]
        }
    }
}

Why This Happens #

Let's break down the root causes here:

• Declarative Pipeline's strict syntax rules
  Declarative Pipeline is a structured, opinionated syntax—you can only use its pre-defined directives (like stage, steps, agent) directly in its blocks. Any plain Groovy code, method calls, or custom step chaining (like gitUtils().cloneRepo(...)) isn't recognized as a valid declarative "symbol", hence the Expected a symbol errors.

• Your custom step's design doesn't fit declarative patterns
  By returning this from the call() method, you're trying to create a fluent interface for method chaining. But Declarative Pipeline doesn't support this style of invocation outside a script block—it expects custom steps to be called as top-level directives, not as method calls on an object.

• Parameter misinterpretation
  The invalid parameter errors (like "Invalid parameter 'url', did you mean 'message'?") happen because Declarative is misinterpreting your method call as one of its built-in steps (likely confusing cloneRepo with the git step). It doesn't understand Groovy's named parameter syntax here because it's not processing the code as plain Groovy.

How to Fix It #

You have a couple of practical options to make this work with Declarative Pipeline:

Option 1: Restructure the custom step to be a single callable directive #

Adjust the call() method to accept parameters directly, so you can call it like a standard Declarative step:

import java.lang.IllegalArgumentException

def call(Map parameters = [url: null, branch: "master", credentials: null]) {
    def url = parameters.getOrDefault("url", null)
    def branch = parameters.getOrDefault("branch", "master")
    def credentials = parameters.getOrDefault("credentials", null)

    if(!url) {
        throw new IllegalArgumentException("gitUtils expects url argument to be present!")
    }
    if(credentials == null) {
        credentials = getCredentials(url)
    }
    if (branch.matches("\\d+") || branch.matches("PR-\\d+")) {
        if (branch.matches("PR-\\d+")) {
            branch = branch.substring(3)
        }
        checkout changelog: false, poll: false, scm: [
            $class: 'GitSCM',
            branches: [[name: 'pr/' + branch]],
            doGenerateSubmoduleConfigurations: false,
            extensions: [[$class: 'LocalBranch', localBranch: 'pr/' + branch]],
            submoduleCfg: [],
            userRemoteConfigs: [[
                credentialsId: credentials,
                refspec: 'refs/pull/' + branch + '/head:pr/' + branch,
                url: url
            ]]
        ]
    } else {
        checkout changelog: false, poll: false, scm: [
            $class: 'GitSCM',
            branches: [[name: branch]],
            doGenerateSubmoduleConfigurations: false,
            extensions: [],
            submoduleCfg: [],
            userRemoteConfigs: [[
                credentialsId: credentials,
                url: url
            ]]
        ]
    }
}

// Keep getCredentials as a private helper method
private def getCredentials(String url) {
    // Your existing credential lookup logic here
}

Now you can call it directly in Declarative without a script block:

pipeline {
    agent any
    stages {
        stage('Clone Repo') {
            steps {
                gitUtils(url: 'https://github.com/your/repo.git', branch: 'main')
            }
        }
    }
}

Option 2: Keep the fluent interface but use script blocks #

If you want to retain the method chaining approach, wrap all gitUtils() calls in a script block. This tells Jenkins to process the code as plain Groovy, which supports your method calls:

pipeline {
    agent any
    stages {
        stage('Clone Repo') {
            steps {
                script {
                    def repo = 'https://github.com/your/repo.git'
                    gitUtils().getCredentials(repo)
                    gitUtils().cloneRepo(url: repo)
                    gitUtils().getRevision()
                }
            }
        }
    }
}

Option 3: Split methods into separate custom steps #

If you want each method (getCredentials, cloneRepo, getRevision) to be usable as standalone Declarative steps, create separate step files for each (e.g., gitCloneRepo.groovy, gitGetCredentials.groovy) or structure your single step to handle different actions via parameters.

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