LibraryConfiguration: extend with allowBRANCH_NAME for literal use of @Library('libname@${BRANCH_NAME}') [JENKINS-69731]

To simplify co-existence of feature-branched pipeline scripts with
feature-branched Jenkins Shared Libraries, allow literal use of
    @Library('libname@${BRANCH_NAME}') _
lines to load a variant of a trusted (global) library with one case
of arbitrary branch naming.

This should be permitted by allowBRANCH_NAME checkbox (independent
of generic allowVersionOverride setting) in the first place.

If enabled, the value of BRANCH_NAME environment variable set by
the current build's Run object would be queried, and if resolvable -
verified with retriever.validateVersion() to match the backend
(Legacy SCM, Modern SCM, and other retrievers like HTTP/ZIP from
workflow-cps-global-lib-http-plugin).

Author: jimklimov

src/main/java/org/jenkinsci/plugins/workflow/libs/LibraryAdder.java

@@ -126,7 +126,7 @@
                     listener.getLogger().println("Only using first definition of library " + name);
                     continue;
                 }
-                String version = cfg.defaultedVersion(libraryVersions.remove(name));
+                String version = cfg.defaultedVersion(libraryVersions.remove(name), build, listener);
                 Boolean changelog = cfg.defaultedChangelogs(libraryChangelogs.remove(name));
                 String source = kind.getClass().getName();
                 if (cfg instanceof LibraryResolver.ResolvedLibraryConfiguration) {

src/main/java/org/jenkinsci/plugins/workflow/libs/LibraryConfiguration.java

@@ -32,6 +32,8 @@
 import hudson.model.Descriptor;
 import hudson.model.DescriptorVisibilityFilter;
 import hudson.model.Item;
+import hudson.model.Run;
+import hudson.model.TaskListener;
 import hudson.util.FormValidation;
 import jenkins.model.Jenkins;
 import org.kohsuke.accmod.Restricted;
@@ -58,6 +60,7 @@ public class LibraryConfiguration extends AbstractDescribableImpl<LibraryConfigu
     private String defaultVersion;
     private boolean implicit;
     private boolean allowVersionOverride = true;
+    private boolean allowBRANCH_NAME = false;
     private boolean includeInChangesets = true;
     private LibraryCachingConfiguration cachingConfiguration = null;
 
@@ -112,6 +115,20 @@ public boolean isAllowVersionOverride() {
         this.allowVersionOverride = allowVersionOverride;
     }
 
+    /**
+     * Whether jobs should be permitted to specify literally @Library('libname@${BRANCH_NAME}')
+     * in pipeline files (from SCM) to try using the same branch name of library as of the job
+     * definition. If such branch name does not exist, fall back to retrieve() defaultVersion.
+     */
+
+    public boolean isAllowBRANCH_NAME() {
+        return allowBRANCH_NAME;
+    }
+
+    @DataBoundSetter public void setAllowBRANCH_NAME(boolean allowBRANCH_NAME) {
+        this.allowBRANCH_NAME = allowBRANCH_NAME;
+    }
+
     /**
      * Whether to include library changes in reported changes in a job {@link #getIncludeInChangesets}.
      */
@@ -140,14 +157,62 @@ public LibraryCachingConfiguration getCachingConfiguration() {
     }
 
     @NonNull String defaultedVersion(@CheckForNull String version) throws AbortException {
+        return defaultedVersion(version, null, null);
+    }
+
+    @NonNull String defaultedVersion(@CheckForNull String version, Run<?, ?> run, TaskListener listener) throws AbortException {
         if (version == null) {
             if (defaultVersion == null) {
                 throw new AbortException("No version specified for library " + name);
             } else {
                 return defaultVersion;
             }
-        } else if (allowVersionOverride) {
+        } else if (allowVersionOverride && !"${BRANCH_NAME}".equals(version)) {
             return version;
+        } else if (allowBRANCH_NAME && "${BRANCH_NAME}".equals(version)) {
+            String runVersion = null;
+            Item runParent = null;
+            if (run != null && listener != null) {
+                try {
+                    runParent = run.getParent();
+                    runVersion = run.getEnvironment(listener).get("BRANCH_NAME", null);
+                } catch (Exception x) {
+                    // no-op, keep null
+                }
+            }
+
+            if (runParent == null || runVersion == null || "".equals(runVersion)) {
+                // Current build does not know a BRANCH_NAME envvar,
+                // or it's an empty string, or this request has null
+                // args for run/listener needed for validateVersion()
+                // below, or some other problem occurred.
+                // Fall back if we can:
+                if (defaultVersion == null) {
+                    throw new AbortException("No version specified for library " + name);
+                } else {
+                    return defaultVersion;
+                }
+            }
+
+            // Check if runVersion is resolvable by LibraryRetriever
+            // implementation (SCM, HTTP, etc.); fall back if not:
+            if (retriever != null) {
+                FormValidation fv = retriever.validateVersion(name, runVersion, runParent);
+
+                if (fv != null && fv.kind == FormValidation.Kind.OK) {
+                    return runVersion;
+                }
+            }
+
+            // No retriever, or its validateVersion() did not confirm
+            // usability of BRANCH_NAME string value as the version...
+            if (defaultVersion == null) {
+                if (runVersion == null)
+                    throw new AbortException("No version specified for library " + name);
+                throw new AbortException("BRANCH_NAME version " + runVersion + " was not found, and no default version specified, for library " + name);
+            } else {
+                return defaultVersion;
+            }
         } else {
             throw new AbortException("Version override not permitted for library " + name);
         }
@@ -172,16 +237,38 @@ public FormValidation doCheckName(@QueryParameter String name) {
         }
 
         @RequirePOST
-        public FormValidation doCheckDefaultVersion(@AncestorInPath Item context, @QueryParameter String defaultVersion, @QueryParameter boolean implicit, @QueryParameter boolean allowVersionOverride, @QueryParameter String name) {
+        public FormValidation doCheckDefaultVersion(@AncestorInPath Item context, @QueryParameter String defaultVersion, @QueryParameter boolean implicit, @QueryParameter boolean allowVersionOverride, @QueryParameter boolean allowBRANCH_NAME, @QueryParameter String name) {
             if (defaultVersion.isEmpty()) {
                 if (implicit) {
                     return FormValidation.error("If you load a library implicitly, you must specify a default version.");
                 }
+                if (allowBRANCH_NAME) {
+                    return FormValidation.error("If you allow use of literal '@${BRANCH_NAME}' for overriding a default version, you must define that version as fallback.");
+                }
                 if (!allowVersionOverride) {
                     return FormValidation.error("If you deny overriding a default version, you must define that version.");
                 }
                 return FormValidation.ok();
             } else {
+                if ("${BRANCH_NAME}".equals(defaultVersion)) {
+                    if (!allowBRANCH_NAME) {
+                        return FormValidation.error("Use of literal '@${BRANCH_NAME}' not allowed in this configuration.");
+                    }
+
+                    // The context is not a particular Run (might be a Job)
+                    // so we can't detect which BRANCH_NAME is relevant:
+                    String msg = "Cannot validate default version: " +
+                            "literal '@${BRANCH_NAME}' is reserved " +
+                            "for pipeline files from SCM";
+                    if (implicit) {
+                        // Someone might want to bind feature branches of
+                        // job definitions and implicit libs by default?..
+                        return FormValidation.warning(msg);
+                    } else {
+                        return FormValidation.error(msg);
+                    }
+                }
+
                 for (LibraryResolver resolver : ExtensionList.lookup(LibraryResolver.class)) {
                     for (LibraryConfiguration config : resolver.fromConfiguration(Stapler.getCurrentRequest())) {
                         if (config.getName().equals(name)) {

src/main/resources/org/jenkinsci/plugins/workflow/libs/LibraryConfiguration/config.jelly

@@ -37,6 +37,9 @@ THE SOFTWARE.
     <f:entry field="allowVersionOverride" title="${%Allow default version to be overridden}">
         <f:checkbox default="true"/>
     </f:entry>
+    <f:entry field="allowBRANCH_NAME" title="${%Allow literal use of @Library 'libname@$${BRANCH_NAME}' in pipeline scripts from SCM; falls back to default version if BRANCH_NAME is not available or not found}">
+        <f:checkbox default="false"/>
+    </f:entry>
     <f:entry field="includeInChangesets" title="${%Include @Library changes in job recent changes}">
         <f:checkbox default="true"/>
     </f:entry>

src/main/resources/org/jenkinsci/plugins/workflow/libs/LibraryConfiguration/help-allowBRANCH_NAME.html

@@ -0,0 +1,9 @@
+<div>
+  If checked, scripts may select a custom version of the library
+  by appending literally <code>@${BRANCH_NAME}</code> in the
+  <code>@Library</code> annotation, to use same SCM branch name
+  of the library codebase as that of the pipeline being built.<br/>
+  If such branch name is not resolvable as an environment variable
+  or not present in library storage (SCM, release artifacts...),
+  it would fall back to default version you select here.
+</div>