Jenkins Build Configuration (jenkins.yaml)

JSON Schemas

jenkins.yaml Jenkins configuration files can be validated with their respective JSON schemas. There is one JSON schema defined per project "type" (service (default), web, mock, library), however, all schemas besides the library schema are equivalent.

They are uniquely named to map directly from the project type to its schema, and also to support if their definitions diverge. However, this is not foreseen nor planned.

Currently, there is one version of these schemas - v1. Updates to the Jenkins configuration file formats will occur sparingly, prioritizing both backward and forward compatibility to the fullest extent feasible. This means, while there may be new optional fields and/or minor changes to the file format, there will not be many breaking changes or renaming of fields.

Default Values

Jenkins Shared Library provides reasonable defaults for fields that likely will not need to be changed, project-to-project. These values are specified in YAML files specific to each project type:

Project Type Default YAML File

service

jenkins-service-default.yaml

web

jenkins-web-default.yaml

mock

jenkins-mock-default.yaml

library

jenkins-library-default.yaml

When reading the project’s jenkins.yaml configuration file, the values set in the corresponding default YAML file are applied first, then each field specified in the project jenkins.yaml overrides the default value.

Default YAML File Contents

Service Project Defaults

jenkins-service-default.yaml
#image: "/ces/cerner-fhir-adapter"
language: java
buildTool: skaffold-maven # skaffold-maven, helm-maven
imageTool: skaffold # skaffold, jib, docker
moduleDir: . # service module directory. If not a multi-module project, use '.'
mavenBuildCommand: mvn install
enableVV: true
enableSonar: true
sonarMainBranchOnly: false
enableQualityGate: true
#sonarReportUrl: 'coderepo.mobilehealth.va.gov/scm/ckm/quality-reports.git'
sonarReportBranch: 'master'
enableManualDeploy: false
enableAutoDeploy: false
enableSlackNotifications: false
slackChannel: ckmbuild
#vvReportUrl: 'coderepo.mobilehealth.va.gov/scm/ckm/vv-reports.git'
publishSnapshots: false
checkImageExists: false
cacheKeyEnabled: false
#jiraProject: CKM
enableOisScan: true
#oisScanCron: '@weekly' # removed in favor of value returned by OIS library
branchesOisScanRegex: '.*'
deferCodeQLInit: false
buildCommandForCodeQL: 'mvn clean install --batch-mode -Dmaven.test.skip -Dmaven.javadoc.skip=true -DskipAll -Dexec.skip=true -Dhelm.skip -Ddocker.skip -Djib.skip -Djacoco.skip=true -Djacoco.dump.skip=true -Pjenkins,jenkins-sandbox,skip-static-analysis'
runNewman: false
enableTagRelease: false
runK6: false
enableFlexline: false

mavenDeployOptsRelease: '-DaltDeploymentRepository=ckm-releases::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-releases'
mavenDeployOptsSnapshot: '-DaltDeploymentRepository=ckm-snapshots::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-snapshots'

sandbox:
  periodicBuild:
    branch: main
    cron: '@weekly'
  branchesToPushImageRegex: '(?i)(release/.*)'
  deployNamespace: default
  deferCodeQLInit: true
  ignoreFlexlineFailure: false

staging: # staging/sqa build environment overrides
  enableAutoDeploy: true
  enableManualDeploy: true
  deployNamespace: sqa
  enableSlackNotifications: true
  checkImageExists: true
  slackFailureChannel: ckmbuildfailures
  branchesToPushImageRegex: '(?i)release/.+'
  deferCodeQLInit: true

prod: # prod build environment overrides
  skip: true
  deployStageOnly: true # disables all but deploy stage
  deployNamespace: prod
  enableAutoDeploy: false
  enableManualDeploy: true

Web Project Defaults

jenkins-web-default.yaml
#image: "/ces/cerner-fhir-adapter"
language: java
buildTool: skaffold-maven # skaffold-maven, helm-maven
imageTool: skaffold # skaffold, jib, docker
moduleDir: . # service module directory. If not a multi-module project, use '.'
mavenBuildCommand: mvn install
enableVV: true
enableSonar: true
sonarMainBranchOnly: false
enableQualityGate: true
#sonarReportUrl: 'coderepo.mobilehealth.va.gov/scm/ckm/quality-reports.git'
sonarReportBranch: 'master'
enableManualDeploy: false
enableAutoDeploy: false
enableSlackNotifications: false
slackChannel: ckmbuild
#vvReportUrl: 'coderepo.mobilehealth.va.gov/scm/ckm/vv-reports.git'
publishSnapshots: false
checkImageExists: false
cacheKeyEnabled: false
#jiraProject: CKM
enableOisScan: true
#oisScanCron: '@weekly' # removed in favor of value returned by OIS library
branchesOisScanRegex: '(?i)(release/.*)'
deferCodeQLInit: false
buildCommandForCodeQL: 'mvn clean install --batch-mode -Dmaven.test.skip -DskipAll -Dhelm.skip -Ddocker.skip -Djib.skip -Djacoco.skip=true -Djacoco.dump.skip=true -Pjenkins,jenkins-sandbox'
enableTagRelease: false
enableFlexline: false

mavenDeployOptsRelease: '-DaltDeploymentRepository=ckm-releases::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-releases'
mavenDeployOptsSnapshot: '-DaltDeploymentRepository=ckm-snapshots::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-snapshots'

sandbox:
  periodicBuild:
    branch: main
    cron: '@weekly'
  branchesToPushImageRegex: '(?i)(release/.*)'
  deployNamespace: default
  ignoreFlexlineFailure: false

staging: # staging/sqa build environment overrides
  enableAutoDeploy: true
  enableManualDeploy: true
  deployNamespace: sqa
  enableSlackNotifications: true
  checkImageExists: true
  slackFailureChannel: ckmbuildfailures
  branchesToPushImageRegex: '(?i)release/.+'
  deferCodeQLInit: true

prod: # prod build environment overrides
  skip: true
  deployStageOnly: true # disables all but deploy stage
  deployNamespace: prod
  enableAutoDeploy: false
  enableManualDeploy: true

Mock Project Defaults

jenkins-mock-default.yaml
#image: "/ces/cerner-fhir-adapter"
language: java
buildTool: skaffold-maven # skaffold-maven, helm-maven
imageTool: skaffold # skaffold, jib, docker
moduleDir: . # service module directory. If not a multi-module project, use '.'
mavenBuildCommand: mvn install
enableVV: false
enableSonar: false
sonarMainBranchOnly: false
enableQualityGate: true
#sonarReportUrl: 'coderepo.mobilehealth.va.gov/scm/ckm/quality-reports.git'
sonarReportBranch: 'master'
enableManualDeploy: false
enableAutoDeploy: false
enableSlackNotifications: false
slackChannel: ckmbuild
#vvReportUrl: 'coderepo.mobilehealth.va.gov/scm/ckm/vv-reports.git'
publishSnapshots: false
checkImageExists: false
cacheKeyEnabled: false
#jiraProject: CKM
enableOisScan: false
mavenDeployOptsRelease: '-DaltDeploymentRepository=ckm-releases::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-releases'
mavenDeployOptsSnapshot: '-DaltDeploymentRepository=ckm-snapshots::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-snapshots'
deferCodeQLInit: false
buildCommandForCodeQL: 'mvn clean install --batch-mode -Dmaven.test.skip -DskipAll -Dhelm.skip -Ddocker.skip -Djib.skip -Djacoco.skip=true -Djacoco.dump.skip=true -Pjenkins,jenkins-sandbox'
enableTagRelease: false
enableFlexline: false

sandbox:
  periodicBuild:
    branch: main
    cron: '@weekly'
  branchesToPushImageRegex: '(?i)(release/.*)'
  deployNamespace: default
  ignoreFlexlineFailure: false

staging: # staging/sqa build environment overrides
  enableSlackNotifications: true
  checkImageExists: true
  slackFailureChannel: ckmbuildfailures
  branchesToPushImageRegex: '(?i)release/.+'
  deferCodeQLInit: true

prod: # prod build environment overrides
  skip: true

Library Project Defaults

jenkins-library-default.yaml
publishSnapshots: false
enableOisScan: false
enableFlexline: false
mavenDeployOptsRelease: '-DaltDeploymentRepository=ckm-releases::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-releases'
mavenDeployOptsSnapshot: '-DaltDeploymentRepository=ckm-snapshots::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-snapshots'
deferCodeQLInit: false

periodicBuild:
  branch: main
  cron: '@weekly'

Environment Defaults and Overrides

The fields sandbox, staging, and prod correspond to the three environments that the project is built with Jenkins. These objects have the same fields available as the "root" level fields (except, of course, themselves), and are used to specify any field values that are specific to that build environment. If there is no override value specified, then the environment-specific build will use the root-level (or default) value.

Example
enableQualityGate: false (1)

sandbox:
  enableQualityGate: true

staging:
  # enableQualityGate: false (2)
1 Project "root"-level value Default values specified within each environment block take precedence over the "root"-level project values. In order to override these values, the project jenkins.yaml must set the value within the environment block.
2 The effective value is false and doesn’t need to be set here because the root/default value is already false and there is no environment-specific default set

For example, given the default staging enableSlackNotifications value of true:

jenkins-default.yaml
staging:
  enableSlackNotifications: true
Project jenkins.yaml
enableSlackNotifications: false (1)

# ...

staging:
  enableSlackNotifications: false (2)
1 Values at the root level override default root-level values, but not environment-level ones
2 The only way to override default environment-level values is to specify within the environment’s specification

Service, Web, and Mock Project Fields

Following are tables that describe all available and required fields in the jenkins.yaml file.

Required fields

Name Type Description Example

image

string

Service container image name

/ckm/my-service

sonarReportUrl

string

(Required if Sonar is enabled) Git repository to store Sonar reports

coderepo.mobilehealth.va.gov/scm/ckm/quality-reports.git

vvReportUrl

string

(Required if V&V is enabled) Git repository to store V&V reports

coderepo.mobilehealth.va.gov/scm/ckm/vv-reports.git

jiraProject

string

(Required if enableOisScan is true) JIRA project key

ckm

Optional fields

Name Type Description Default Value

artifactId

string

Maven artifact ID

pom.xml artifactId

groupId

string

Maven group ID

pom.xml groupId

version

string

Project version

pom.xml version

language

enum

java,go, javascript: programming language used by service

java

buildTool

enum

skaffold-maven, helm-maven, skaffold-ko

skaffold-maven

imageTool

enum

skaffold, jib, docker

skaffold

moduleDir

string

Relative file path from project directory to Maven service module (working directory)

.

mavenBuildCommand

string

Maven command to build service

mvn install

enableVV

boolean

Enable V&V stage and build/report options

true

enableSonar

boolean

Enable Sonar stage and build/report options

true

sonarMainBranchOnly

boolean

Only publish Sonar reports on main* branches

false

sonarReportBranch

string

The branch of the Sonar reports repo to edit

master

enableQualityGate

boolean

Enable Sonar quality gate

true

enableManualDeploy

boolean

Enable manual Jenkins job-based deployment to Kubernetes cluster

false

enableAutoDeploy

boolean

Enable auto-deployment post-build to Kubernetes cluster

false

enableSlackNotifications

boolean

Enable Slack notifications to be sent on build actions and results

false

slackChannel

string

Slack channel to publish notifications

ckmbuild

publishSnapshots

boolean

Enable publshing of Maven snapshot builds to snapshot repository

false

checkImageExists

boolean

Enable pre-build check for the existence of same image in the DTR

false

cacheKeyEnabled

boolean

Enable dependence on Caché key

false

jiraComponent

string

JIRA component name

enableOisScan

boolean

Enable OIS scan capability

true

branchesOisScanRegex

regex

Regular expression of branches to run OIS scan on

(?i)(main|release/.*)

deferCodeQLInit

boolean

Run additional trace build using the command supplied in buildCommandForCodeQL

false

buildCommandForCodeQL

string

Command to run when deferCodeQLInit is true

mvn clean install --batch-mode -Dmaven.test.skip -Pskip-all-generation -Dhelm.skip -Ddocker.skip -Djib.skip -Djacoco.skip=true -Djacoco.dump.skip=true -Pjenkins,jenkins-sandbox

mavenDeployOptsRelease

string

Maven options to include in the post-build mvn deploy command on Release/* branches

-DaltDeploymentRepository=ckm-releases::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-releases

mavenDeployOptsSnapshot

string

Maven options to include in the post-build mvn deploy command on main* branches

-DaltDeploymentRepository=ckm-snapshots::default::https://nexus.mobilehealth.va.gov/content/repositories/ckm-snapshots

periodicBuild (see below)

object

Schedule periodic builds of service

pushAllBranchImages

boolean

Push images from all branches to the DTR

false

branchesToPushImageRegex

regex

Regular expression of branches to push the image to the DTR

deployStageOnly

boolean

Only include the Deploy stage in the build definition

false

deployNamespace

string

The Kubernetes namespace to deploy the application to for manual and automatic deployments

postDeployHookCmd

string

(Service only) Command to run after deployment completes

slackFailureChannel

string

The Slack channel to send messages to on build failures

skip

boolean

Completely skip build of service

false

runNewman

boolean

(Service only) Enable Newman (Postman) test execution

false

runK6

boolean

(Service only) Enable k6 performance test execution

false

enableTagRelease

boolean

Enable tagging of releases

false

enableFlexline

boolean

Enable Flexline integration

false

customParameters (see below)

array

Define project-specific build parameters to be used as environment variables

sandbox

object

Values in the Sandbox environment to override

 
periodicBuild:
  branch: main
  cron: '@weekly'
branchesToPushImageRegex: '(?i)(release/.*)'
deployNamespace: default

staging

object

Values in the Staging/SQA environment to override

 
enableAutoDeploy: true
enableManualDeploy: true
deployNamespace: sqa
enableSlackNotifications: true
checkImageExists: true
slackFailureChannel: ckmbuildfailures
branchesToPushImageRegex: '(?i)release/.+'

prod

object

Values in the Production environment to override

 
skip: true
deployStageOnly: true # disables all but deploy stage
deployNamespace: prod
enableAutoDeploy: false
enableManualDeploy: true

Periodic Build Type

The periodicBuild field is a complex object that specifies automatic scheduled builds using cron-style syntax. The following fields are valid for this object:

Name Type Description

branch

string

The Git branch to schedule builds for

cron

string

The cron-formatted value that defines when to build. See https://www.cloudbees.com/blog/how-to-schedule-a-jenkins-job.

Custom Parameters

The customParameters field is an array of items which have the following structure:

Name Type Description

name

string

The name of the build parameter

type

enum [string, booleanParam]

The type of Jenkins build parameter

description

string

Description of the parameter that is displayed in the Jenkins build UI alongside the parameter

defaultValue

string or boolean

The default value of the build parameter, unless set via configKey

configKey

string

The jenkins.yaml field to set as the default value

environmentVariable

string

When this is present, an environment variable with this name is set to the provided value

Environment Default Values

Following are the default values for each environment for the service project type:

sandbox:
  periodicBuild:
    branch: main
    cron: '@weekly'
  branchesToPushImageRegex: '(?i)(release/.*)'
  deployNamespace: default

staging: # staging/sqa build environment overrides
  enableAutoDeploy: true
  enableManualDeploy: true
  deployNamespace: sqa
  enableSlackNotifications: true
  checkImageExists: true
  slackFailureChannel: ckmbuildfailures
  branchesToPushImageRegex: '(?i)release/.+'
  deferCodeQLInit: true

prod: # prod build environment overrides
  skip: true
  deployStageOnly: true # disables all but deploy stage
  enableAutoDeploy: false
  enableManualDeploy: true