Jenkins pipeline library using the Ontrack GraphQL API.
JCasC (Jenkins Configuration as Code) is the recommended approach:
globalLibraries:
libraries:
- name: "ontrack-jenkins-cli-pipeline"
retriever:
modernSCM:
scm:
github:
configuredByUrl: true
credentialsId: "<GitHub credentials>"
repositoryUrl: "https://github.com/nemerosa/ontrack-jenkins-cli-pipeline"
You can also use the Jenkins management UI to register this library:
The steps provided by this library, in order to avoid redundant configuration, rely on predefined environment variables and credentials.
Those environment variables and credentials are not strictly required but they will ease the use of the Ontrack steps.
In most of the cases, you just need to define:
ONTRACK_URL
- URL to OntrackONTRACK_TOKEN
- secret text credentials entry containing the authentication token used to connect to Ontrack
See ontrackCliSetup
for more information.
In your Jenkinsfile
, declare the version of the pipeline library you want to use and start using the steps
provided by the library. For example:
@Library("ontrack-jenkins-cli-pipeline@main") _
pipeline {
agent any
stages {
stage("Setup") {
steps {
// Ontrack connection & branch setup
ontrackCliSetup()
}
}
stage("Preparation") {
steps {
// Computing a version in VERSION
// Ontrack build entry creation
ontrackCliBuild(release: env.VERSION)
}
post {
always {
// Validation run, including detection of the
// status and run information
ontrackCliValidate(stamp: 'STAMP')
}
}
}
}
}
Most of the steps accept a logging
parameter but logging can be configured globally using
the ONTRACK_LOGGING
environment variable, set to false
or true
(false
is the default).
Note that any
logging
parameter on the step will override the global settings.
Typically, the ONTRACK_LOGGING
environment variable would be set at pipeline level:
pipeline {
environment {
ONTRACK_LOGGING = true
}
}
In this example, we use the main
branch of the pipeline library but it's better to stick to:
- versioned branches, like
v1
- or explicit tags in order to ensure build reproducibility. See the list of available tags in GitHub.
ontrackCliSetup
- general purpose setup task to set up Ontrack in your pipeline, from creating common environment variables to initializing project and branch in Ontrack for your pipeline.ontrackCliSetupSonarQube
- setup of SonarQube properties at project level
ontrackCliBuild
- creates an Ontrack build entry based on current informationontrackCliPromote
- creates an Ontrack promotion run for the current build, based on current information or provided informationontrackCliValidate
- creates an Ontrack validation run for the current build, based on current information or provided informationontrackCliValidateTests
- creates an Ontrack validation run based on JUnit test resultsontrackCliValidateWithTestResults
- same as above but reuses existing JUnit tst resultsontrackCliValidateCHML
- creates an Ontrack validation run based on critical/high/medium/low statsontrackCliValidatePercentage
- creates an Ontrack validation run based on a percentageontrackCliValidateMetrics
- creates an Ontrack validation run based on a map of metrics
ontrackCliBuildMessage
- setting a message property on an existing buildontrackCliBuildMetaInfo
- setting or updating a meta-info property on an existing build- `ontrackCliBuildGitCommit - setting or updating the "Git commit" property on an existing build
ontrackCliBuildLink
- creates a link to another buildontrackCliBuildLinks
- creates several link other builds
ontrackCliLastBranch
- getting the last branch for given patternontrackCliLastPromotion
- getting the last build for a given promotionontrackCliLastPromotionByProject
- getting the last build for a given promotion over all branchesontrackCliGetBuildByVersion
- getting a build using its release/label/version propertyontrackCliGetBuildByMetaVersion
- getting a build using a version stored in its meta informationontrackCliGetBuildByProjectAndVersion
- getting a build using its release/label/version property inside a projectontrackCliGetBuildByCommit
- getting a build in the current branch using its commit
ontrackCliAutoVersioning
- setting up the auto versioning for the branchontrackCliAutoVersioningProject
- setting up the auto versioning rules at project levelontrackCliAutoVersioningCheck
- checking the auto versioning alignment and creating a corresponding validation
ontrackCliSetupProjectNotifications
- setup of notifications at project levelontrackCliSetupBranchNotifications
- setup of notifications at branch levelontrackCliSetupPromotionLevelNotifications
- setup of notifications at promotion levelontrackCliSetupValidationStampNotifications
- setup of notifications at validation stamp level
ontrackCliGraphQL
- performs a GraphQL call to Ontrack and returns the JSON response
These steps are very specific in the kind of scenario they are running and interact with more than Ontrack.
ontrackCliCheckoutConditionalOnPromotionAndTrigger
- performs a SCM checkout based on the nature of the trigger
Those steps allow to download and the setup the Ontrack CLI.
ontrackCliDownload
- downloads the Ontrack CLI and sets it into the pathontrackCliConnect
- creates a connection configuration for the Ontrack CLI, based on provided information or the environment
You can run the Ontrack steps in a mode where any error is ignored.
Note that steps returning values will then return a null or empty value. This may cause some issues in some pipelines relying on these values, so it's not a perfect solution.
Set the ONTRACK_IGNORE_ERRORS
global environment variable to true
.
In case you want to utterly disable all the Ontrack steps, in all pipelines, to do something and in particular,
you want to remove any connection to the Ontrack server, you can set the ONTRACK_STOP
global environment
variable to true
.
Like when ignoring errors, the steps returning values will return a null or empty value. This may cause some issues in some pipelines relying on these values, so it's not a perfect solution.
Variable | Default value | Description |
---|---|---|
ONTRACK_LOGGING | false |
Enabling by default logging for all Ontrack operations |
ONTRACK_URL | Required | URL to the Ontrack server |
ONTRACK_TOKEN | Required | API token used to connect to Ontrack |
ONTRACK_STOP | false |
See Failsafe |
ONTRACK_IGNORE_ERRORS | false |
See Ignoring errors |
ONTRACK_USE_LABEL | false |
See ontrackCliSetup |
ONTRACK_SCM | github |
See ontrackCliSetup |
ONTRACK_SCM_CONFIG | github.com |
See ontrackCliSetup |
ONTRACK_SCM_ISSUES | `` | See ontrackCliSetup |