jenkins.yaml Configuration Reference

The jenkins.yaml file in your project root defines how JSL orchestrates your build and deployment pipeline. This is the contract between your project configuration and JSL’s automation.

Core Configuration Keys

Build & Language

Key Type Default Required Description

image

string

✓

Docker image repository path (e.g., /ckm/my-service)

language

string

java

Programming language: java, javascript, go

buildTool

string

skaffold-maven

Build orchestration: skaffold-maven, helm-maven, docker

imageTool

string

skaffold

Image building tool: skaffold, jib, docker

moduleDir

string

.

Project directory (use . for single-module projects)

Artifact & Versioning

Key Type Default Required Description

groupId

string

Maven group ID (auto-detected from pom.xml if not set)

artifactId

string

Maven artifact ID (auto-detected from pom.xml if not set)

version

string

Project version (auto-detected from pom.xml if not set)

majorVersion

string

Major version number (auto-detected from pom.xml if not set)

deployVersion

string

Override version for deployments (defaults to version)

Deployment

Key Type Default Required Description

deployNamespace

string

Target Kubernetes namespace for deployment

deployStageOnly

boolean

false

Skip build/test stages; deploy only

enableAutoDeploy

boolean

Auto-deploy to target environments (when enabled in JSL config)

branchesToPushImageRegex

string

Git branch regex to trigger image push (e.g., ^(main|release/.*)$)

checkImageExists

boolean

Check if image already exists before rebuilding

Scanning & Quality

Key Type Default Required Description

jiraProject

string

JIRA project key (required for OIS scan)

enableOisScan

boolean

true

Enable OIS security scanning

enableSonar

boolean

Enable SonarQube scanning

sonarReportUrl

string

SonarQube server URL for publishing results

sonarReportBranch

string

Branch to report Sonar results to (defaults to current branch)

sonarMainBranchOnly

boolean

Run Sonar only on main branch

enableQualityGate

boolean

Enforce SonarQube quality gates (fail build if gates fail)

Notifications

Key Type Default Required Description

enableSlackNotifications

boolean

Send Slack notifications on build events

slackChannel

string

Slack channel for success notifications (without #)

slackFailureChannel

string

Slack channel for failure notifications (without #)

Advanced / Release

Key Type Default Required Description

enableTagRelease

boolean

Tag repository on successful build (requires gitRepo)

gitRepo

string

Git repository URL for release tagging

mavenDeployOptsSnapshot

string

Maven options for snapshot artifact deployment

mavenDeployOptsRelease

string

Maven options for release artifact deployment

skip

boolean

Skip the entire pipeline (useful for temporary disables)

cacheKeyEnabled

boolean

Enable credential caching (optimization)

Periodic & Special Builds

Key Type Default Required Description

periodicBuild

object

Configure cron-based periodic builds

periodicBuild.branch

string

Git branch to run periodic build on

periodicBuild.cron

string

Cron expression (e.g., 0 2 * * * for 2 AM daily)

runNewman

boolean

Enable API testing via Postman Newman

Adding New Configuration Keys to JSL

When you need to add a new configuration option:

  1. Add it to the JSL groovy file that handles that stage (e.g., buildServiceProject.groovy, sonarScan.groovy)

    • Extract the value: def myNewKey = config.myNewKey ?: defaultValue

    • Use it in your logic

  2. Document the key in this reference with type, default, required status, and description

  3. Add an example in one of the example files (jenkins-service-example.yaml, jenkins-web-example.yaml, etc.) if it’s commonly used

  4. Update the JSL CHANGELOG noting the new configuration option and when it was introduced

  5. Test with a real project to ensure the key is read and used correctly

  6. Consider backwards compatibility — if changing an existing key’s behavior, ensure old configurations still work or provide a clear migration path

Example jenkins.yaml Files

See the JSL repository examples/ directory for complete, commented examples:

  • jenkins-service-example.yaml — Java backend service

  • jenkins-web-example.yaml — JavaScript frontend

  • jenkins-library-example.yaml — Shared library projects

  • jenkins-mock-example.yaml — Mock services

Overriding jenkins.yaml Values at Runtime

Some JSL functions support dynamic parameter overrides:

  • DEPLOY_NAMESPACE — override deployment namespace

  • DEPLOY_VERSION — override version to deploy

  • RUN_SONAR_ONLY — run only Sonar scanning stage

Check individual JSL function documentation for additional runtime parameters.