Library directory structure in Jenkins - Commands & Configuration

Introduction

When you build many Jenkins pipelines, you often reuse code. The library directory structure helps organize this reusable code so you can share it easily across projects.

When you want to share common pipeline steps between multiple Jenkins jobs without copying code.

When you want to keep your pipeline code clean by moving complex logic to separate files.

When you want to update shared pipeline code in one place and have all jobs use the new version.

When you want to organize helper functions, classes, or scripts used by your Jenkins pipelines.

When you want to separate pipeline code by teams or projects but still keep it in one place.

Config File - vars/mySharedStep.groovy

vars/mySharedStep.groovy

def call(String name) {
    echo "Hello, ${name}! This is a shared step."
}

This file defines a shared step named mySharedStep in the vars directory. The call method allows this step to be used like a function in Jenkins pipelines. The vars folder is where you put reusable pipeline steps.

Commands

Create the directory structure for the shared library inside Jenkins home directory. The vars folder holds reusable pipeline steps.

Terminal

mkdir -p /var/jenkins_home/shared-libraries/vars

Expected Output

No output (command runs silently)

Create a Groovy file defining a shared step named mySharedStep that prints a greeting message. This file goes inside the vars directory.

Terminal

echo 'def call(String name) {\n    echo "Hello, ${name}! This is a shared step."\n}' > /var/jenkins_home/shared-libraries/vars/mySharedStep.groovy

Expected Output

No output (command runs silently)

Create a Jenkins pipeline job that uses the shared library. This command uploads the job configuration to Jenkins.

Terminal

java -jar jenkins-cli.jar -s http://localhost:8080/ create-job my-pipeline < my-pipeline-config.xml

Expected Output

Created job: my-pipeline

Trigger a build of the Jenkins pipeline job to test if the shared library step works.

Terminal

curl -X POST http://localhost:8080/job/my-pipeline/build --user admin:admin123

Expected Output

Started build #1

Key Concept

If you remember nothing else from this pattern, remember: the vars directory inside a Jenkins shared library holds reusable pipeline steps as Groovy scripts.

Common Mistakes

Placing shared step Groovy files outside the vars directory.

Jenkins only recognizes reusable steps inside the vars folder; files elsewhere won't be loaded automatically.

Always put reusable pipeline step scripts inside the vars directory in your shared library.

Not defining a call method in the Groovy file for the shared step.

Without a call method, Jenkins cannot invoke the step like a function in pipelines.

Define a call method in your Groovy script to make the step callable.

Forgetting to configure the shared library in Jenkins global settings.

Jenkins won't know where to find your shared library code without proper configuration.

Add the shared library path in Jenkins global configuration under 'Configure System'.

Summary

Create a shared library directory with a vars folder to hold reusable pipeline steps.

Write Groovy scripts with a call method inside vars to define shared steps.

Use Jenkins CLI or UI to create pipeline jobs that use the shared library.

Trigger builds to verify the shared steps work as expected.

Practice

1. What is the primary purpose of the vars/ directory in a Jenkins shared library?

easy

A. To store simple Groovy scripts accessible as global variables

B. To store compiled Java classes

C. To hold configuration files like YAML or JSON

D. To keep pipeline job definitions

Solution

1. Step 1: Understand the role of vars/ directory

   The vars/ directory is used to store simple Groovy scripts that Jenkins loads as global variables or functions.

2. Step 2: Differentiate from other directories

   The src/ directory is for classes, and resources/ is for config files, so vars/ is specifically for simple scripts.

3. Final Answer:

   To store simple Groovy scripts accessible as global variables -> Option A

4. Quick Check:

   vars/ = simple scripts [OK]

Hint: Remember: vars = simple scripts, src = classes, resources = configs [OK]

Common Mistakes:

• Confusing vars/ with src/ directory
• Thinking vars/ holds config files
• Assuming vars/ stores compiled classes

2. Which directory should you place a Groovy class file named MyHelper.groovy in a Jenkins shared library?

easy

A. src/

B. vars/

C. resources/

D. jobs/

Solution

1. Step 1: Identify the purpose of src/ directory

   The src/ directory is meant for Groovy or Java classes in a Jenkins shared library.

2. Step 2: Match the file type to directory

   Since MyHelper.groovy is a class file, it belongs in src/, not vars/ or resources/.

3. Final Answer:

   src/ -> Option A

4. Quick Check:

   Classes go to src/ [OK]

Hint: Classes always go inside src/ folder [OK]

Common Mistakes:

• Placing class files in vars/
• Putting Groovy classes inside resources/
• Using non-existent jobs/ directory

3. Given this Jenkins shared library structure:
vars/notify.groovy
src/org/example/Helper.groovy
resources/config/settings.yml
Which file would you use to load configuration settings inside a pipeline?

medium

A. vars/notify.groovy

B. resources/config/settings.yml

C. vars/settings.yml

D. src/org/example/Helper.groovy

Solution

1. Step 1: Identify the purpose of resources/ directory

   The resources/ directory holds static files like configuration files (YAML, JSON) used by the library.

2. Step 2: Match the file type to usage

   Since settings.yml is a config file, it should be loaded from resources/config/settings.yml.

3. Final Answer:

   resources/config/settings.yml -> Option B

4. Quick Check:

   Config files = resources/ [OK]

Hint: Config files always go in resources/ [OK]

Common Mistakes:

• Trying to load config from vars/
• Confusing class files with config files
• Assuming config files go in src/

4. You placed a Groovy script build.groovy inside resources/ directory. What issue will you face when trying to call build() in your Jenkins pipeline?

medium

A. The script will run normally without issues

B. The script will be compiled but not executed

C. Jenkins will throw a missing method error because resources/ is for static files only

D. The pipeline will ignore the script and continue silently

Solution

1. Step 1: Understand the role of resources/ directory

   The resources/ directory is only for static files like configs, not executable Groovy scripts.

2. Step 2: Consequence of placing script in resources/

   Since build.groovy is not in vars/ or src/, Jenkins cannot load it as a callable method, causing a missing method error.

3. Final Answer:

   Jenkins will throw a missing method error because resources/ is for static files only -> Option C

4. Quick Check:

   Scripts must be in vars/ or src/ [OK]

Hint: Scripts in resources/ cause missing method errors [OK]

Common Mistakes:

• Expecting Groovy scripts to run from resources/
• Ignoring directory purpose and mixing files
• Assuming silent failure without error

5. You want to create a reusable Jenkins shared library that includes:
- A global function notifyBuild
- A helper class BuildHelper
- A configuration file email.yml
Which directory structure correctly organizes these files?

hard

A. src/notifyBuild.groovy, vars/BuildHelper.groovy, resources/email.yml

B. vars/notifyBuild.groovy, resources/BuildHelper.groovy, src/email.yml

C. resources/notifyBuild.groovy, src/BuildHelper.groovy, vars/email.yml

D. vars/notifyBuild.groovy, src/BuildHelper.groovy, resources/email.yml

Solution

1. Step 1: Assign global functions to vars/

   Global functions like notifyBuild go into vars/ as Groovy scripts.

2. Step 2: Place helper classes in src/

   Classes like BuildHelper belong in src/ directory.

3. Step 3: Store config files in resources/

   Configuration files such as email.yml must be inside resources/.

4. Final Answer:

   vars/notifyBuild.groovy, src/BuildHelper.groovy, resources/email.yml -> Option D

5. Quick Check:

   vars = functions, src = classes, resources = configs [OK]

Hint: Match file type: vars=func, src=class, resources=config [OK]

Common Mistakes:

• Swapping vars/ and src/ for functions and classes
• Placing config files outside resources/
• Mixing file types in wrong directories