How Are Jenkins Scripts Organized in the Jenkins Core Repository

Jenkins organizes its script assets into five distinct architectural layers: a top-level Jenkinsfile for CI orchestration, Groovy UI fragments under core/src/main/resources, reusable shared libraries in core/src/main/resources/lib, test fixtures in test/src/test/resources, and Java-based core implementations that provide the Pipeline DSL runtime.

The jenkinsci/jenkins repository separates concerns between pipeline definition, runtime Groovy helpers, and core Java implementation to maintain extensibility and security. Understanding how scripts are organized helps developers navigate the codebase, create custom pipeline steps, and extend the UI without recompiling Java sources.

Pipeline Entry Point: The Root Jenkinsfile

The repository root contains a single Jenkinsfile that serves as the single source of truth for how Jenkins builds itself. This Declarative Pipeline orchestrates stages such as checkout, compilation, testing, and packaging.

// https://github.com/jenkinsci/jenkins/blob/master/Jenkinsfile
pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps { checkout scm }
        }
        stage('Build') {
            steps { sh './mvnw clean install -DskipTests' }
        }
        stage('Test') {
            steps { sh './mvnw test' }
        }
        // … additional stages …
    }
    post {
        always { archiveArtifacts '**/target/*.jar' }
    }
}

This file demonstrates the canonical layout of a Jenkins pipeline script, using standard steps like checkout scm and sh to drive the build process.

A complete stand-alone Declarative Pipeline example:

pipeline {
    agent any
    environment {
        MVN_OPTS = '-B -DskipTests'
    }
    stages {
        stage('Compile') {
            steps { sh './mvnw clean compile $MVN_OPTS' }
        }
        stage('Unit Test') {
            steps { sh './mvnw test' }
        }
        stage('Package') {
            steps { sh './mvnw package' }
        }
    }
    post {
        success { archiveArtifacts 'target/*.jar' }
        failure { mail to: 'dev@example.com', subject: 'Build failed', body: 'Check console' }
    }
}

Groovy UI and Configuration Scripts

Jenkins uses Groovy scripts to render dynamic UI components and configuration forms. These fragments reside under core/src/main/resources and are loaded at runtime by the Stapler web framework, allowing rapid UI changes without Java recompilation.

For example, the project naming strategy configuration uses:

// core/src/main/resources/jenkins/model/ProjectNamingStrategy/PatternProjectNamingStrategy/config.groovy
f.textarea(name: "pattern", value: instance.pattern, rows: 5)

Another common pattern appears in global configuration pages:

// core/src/main/resources/jenkins/model/GlobalPluginConfiguration/config.groovy
f.entry(title: _('Plugin List')) {
    f.textarea(name: "pluginList", rows: 10, value: instance.pluginList)
}

These scripts are namespace-scoped by their directory hierarchy, with paths mirroring the Java package structure of the corresponding classes.

Shared Library Scripts for Reusable Functions

The core/src/main/resources/lib directory hosts shared libraries such as pipeline-utilities that expose helper methods consumable by any pipeline via the @Library annotation. These reusable functions serve as building blocks for larger pipelines.

The following example defines a simple greeting function:

// core/src/main/resources/lib/form/OptionTest/UsingGroovyView/index.groovy
def hello(name) {
    echo "Hello, ${name}!"
}
return this

Pipeline authors import and execute these functions using:

@Library('jenkinsci/jenkins') _
hello('World')

You can also load library resources directly:

@Library('jenkinsci/jenkins') _
def utils = libraryResource 'jenkins/model/ProjectNamingStrategy/PatternProjectNamingStrategy/config.groovy'
utils.hello('Jenkins')

This separation allows the core repository to maintain common utilities while keeping individual Jenkinsfiles clean and focused on business logic.

Test Fixture Scripts

Under test/src/test/resources, Jenkins stores Groovy snippets used by unit and integration tests to validate the pipeline parser, security whitelists, and Stapler routing. These fixtures illustrate how the engine processes edge cases such as pipeline-specific DSL extensions and tag library interactions.

// test/src/test/resources/jenkins/security/stapler/StaplerDispatchValidatorTest/Groovy/index.groovy
def hello() { return "test" }

Test scripts provide regression coverage and serve as executable documentation for expected Groovy behavior within the Jenkins security model.

Core Java Implementation Layer

While Groovy handles orchestration and UI, the heavy lifting of pipeline execution lives in Java classes under core/src/main/java. Classes like WorkflowRun, Step, and FlowNode implement the Pipeline DSL that Groovy scripts invoke at runtime.

For example, ArtifactArchiver provides the backing implementation for artifact collection:

// core/src/main/java/hudson/tasks/ArtifactArchiver.java
public class ArtifactArchiver extends AbstractArtifactArchive {
    // …
}

This Java core guarantees type safety and performance while exposing a Groovy-friendly DSL facade. The strict separation ensures that user scripts execute safely within the sandbox, with the Java engine enforcing security boundaries.

Summary

• Top-level pipeline (Jenkinsfile) – Controls the CI flow for the Jenkins core project itself, located at the repository root.
• Groovy UI/config scripts – Reside in core/src/main/resources/**/*.groovy and render configuration pages via the Stapler framework.
• Shared libraries – Live under core/src/main/resources/lib/**/*.groovy and are consumable via the @Library annotation.
• Test scripts – Provide examples and regression coverage in test/src/test/resources/**/*.groovy.
• Java core – Provides the DSL and runtime semantics through classes like WorkflowRun, Step, and FlowNode in core/src/main/java.

Frequently Asked Questions

Where is the main Jenkinsfile located in the jenkinsci/jenkins repository?

The main Jenkinsfile is located at the repository root (/Jenkinsfile). This Declarative Pipeline defines how the Jenkins core project builds itself, orchestrating stages for checkout, Maven compilation, testing, and artifact archival.

What is the purpose of Groovy scripts in core/src/main/resources?

These scripts generate dynamic HTML for configuration forms and UI pages. Loaded by the Stapler web framework at runtime, they allow developers to modify UI logic without recompiling Java code. Files like core/src/main/resources/jenkins/model/ProjectNamingStrategy/PatternProjectNamingStrategy/config.groovy define form fields using the f namespace (Form Taglib).

How do shared libraries work in Jenkins core?

Shared libraries in core/src/main/resources/lib expose reusable Groovy functions that pipeline authors can import using @Library('jenkinsci/jenkins') _. These libraries encapsulate common operations such as environment setup or artifact handling, promoting code reuse across multiple pipelines without duplication.

What is the difference between Groovy scripts and Java classes in Jenkins architecture?

Groovy scripts handle orchestration (Jenkinsfiles), UI rendering (config pages), and test fixtures, providing flexibility and rapid iteration. Java classes in core/src/main/java implement the core runtime engine, including classes like WorkflowRun and Step, which provide the type-safe DSL that Groovy scripts consume. The Java layer enforces security boundaries and performance guarantees while exposing a scriptable Groovy facade.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}