Global shared library configuration in Jenkins - Commands & Configuration

Introduction

When you have multiple Jenkins pipelines that share common code, you can put that code in a global shared library. This helps you avoid repeating the same code in many places and makes updates easier.

When you want to reuse pipeline steps across different Jenkins jobs without copying code.

When you need to update a common function and want all pipelines to use the new version automatically.

When you want to organize your pipeline code better by separating reusable parts.

When you want to share helper scripts or utilities between multiple Jenkinsfiles.

When you want to keep your Jenkinsfiles simple by moving complex logic to a shared library.

Config File - config.xml

config.xml

<?xml version="1.0" encoding="UTF-8"?>
<com.cloudbees.plugins.credentials.SystemCredentialsProvider>
  <domainCredentialsMap class="linked-hash-map">
    <entry>
      <com.cloudbees.plugins.credentials.domains.Domain>
        <specifications/>
      </com.cloudbees.plugins.credentials.domains.Domain>
      <java.util.concurrent.CopyOnWriteArrayList/>
    </entry>
  </domainCredentialsMap>
</com.cloudbees.plugins.credentials.SystemCredentialsProvider>

This is a minimal example of Jenkins system configuration XML. However, global shared libraries are configured via Jenkins UI or Groovy scripts, not directly by editing config.xml. The actual shared library configuration is stored inside Jenkins system configuration and managed through the UI under Manage Jenkins > Configure System > Global Pipeline Libraries.

For automation, you can use a Groovy script to define global shared libraries in Jenkins startup scripts or via the Jenkins script console.

Commands

This command uses Jenkins CLI to run a Groovy script that configures a global shared library in Jenkins. It automates adding the shared library without using the UI.

Terminal

jenkins-cli.jar -s http://localhost:8080 groovy = < globalSharedLibrary.groovy

Expected Output

Running script...

Library configured successfully

→

-s - Specifies the Jenkins server URL

Shows the Groovy script content that defines the global shared library configuration.

Terminal

cat globalSharedLibrary.groovy

Expected Output

import jenkins.model.*

import org.jenkinsci.plugins.workflow.libs.*



// Define the global shared library

LibraryConfiguration libConfig = new LibraryConfiguration('my-shared-lib')

libConfig.setDefaultVersion('main')

libConfig.setImplicit(true)

libConfig.setAllowVersionOverride(true)



// Set SCM source (Git)

GitSCMSource scmSource = new GitSCMSource('https://github.com/example/my-shared-lib.git')

libConfig.setSource(scmSource)



// Add the library to Jenkins global configuration

Jenkins.instance.getDescriptorByType(GlobalLibraries.class).setLibraries([libConfig])

Jenkins.instance.save()

Lists all configured global shared libraries in Jenkins to verify the new library is added.

Terminal

jenkins-cli.jar -s http://localhost:8080 list-libraries

Expected Output

my-shared-lib (default: main, implicit: true, allowVersionOverride: true)

→

-s - Specifies the Jenkins server URL

Key Concept

If you remember nothing else from this pattern, remember: global shared libraries let you write reusable pipeline code once and use it everywhere in Jenkins.

Common Mistakes

Trying to configure global shared libraries by editing Jenkins config.xml directly.

Jenkins stores global shared library settings internally and expects configuration via UI or Groovy scripts, not manual XML edits.

Use the Jenkins UI under Manage Jenkins > Configure System or automate with Groovy scripts via Jenkins CLI or startup scripts.

Not setting the library as implicit or default version, causing pipelines to fail to find the library.

If the library is not implicit or no default version is set, Jenkins pipelines must specify the library version explicitly, which can cause errors if omitted.

Set the library as implicit and provide a default version to simplify usage in pipelines.

Summary

Use Groovy scripts or Jenkins UI to configure global shared libraries for reusable pipeline code.

Run Jenkins CLI commands to apply and verify the shared library configuration.

Set default version and implicit usage to make the library easy to use in pipelines.