Declare jenkins pipelines using a json configuration file.
This uses an example configuration of this project to demo features, it expects that you have golang installed:
- clone this project
- run
make example
- adjust the file
Pipeline.example
to point to your test jenkins server - execute
./ppl-example create
-- repeat until no errors are reported (it'll complain on missing jenkins plugins which you will need to install) - open url that is displayed
- either wait ~1 minute or trigger the job called
test-pipeline
by hand and go back to the pipeline view - in order to delete the pipeline and its jobs again call
./ppl-example delete test-pipeline
the configuration for this pipeline:
looks as follows:
{
"stages": [
{
"name": "stage0",
"jobs": [
{ "job0": {"cmd": "echo 'job0'; mv spec spec2", "artifacts": ["spec2/"] } },
{ "job1": "echo 'job1'; find ." }
],
"next-stages": [ "stage1" ]
},
{
"name": "stage1",
"jobs": [
{ "job2": {"cmd": "echo 'job2'; cp -a spec spec1; cp -a spec spec2", "artifacts": ["spec1/","spec2/"] } },
[
{ "job4": {"cmd": "echo 'job4'; mv spec1 spec3", "artifacts": ["spec3/"]} },
{ "job5": {"cmd": "echo 'job5'; mv spec2 spec4", "artifacts": ["spec4/"]} }
]
],
"next-stages": [ "stage2" ]
},
{
"name": "stage2",
"jobs": [
[
{ "job7": {"cmd": "echo 'job7'", "no-clean": true} },
{ "job8": "echo 'job8'" }
]
],
"next-stages": [ "stage3" ]
},
{
"name": "stage3",
"jobs": [
[
{ "job10": {"cmd": "echo 'job10'", "artifacts": ["art1"]} },
{ "job11": {"cmd": "echo 'job11'", "artifacts": ["art2"]} }
],
{ "job12": "echo notify" }
],
"next-stages": [ "stage4", "stage5" ]
},
{
"name": "stage4",
"jobs": [
{ "job13": {"cmd": "echo 'job13'", "manual": true} }
]
},
{
"name": "stage5",
"jobs": [
{ "job14": "echo 'job14'" },
{ "job15": "echo 'job15'" }
]
}
],
"settings": {
"jenkins-server": "http://jenkins:8080",
"git-url": "http://github.com/kesselborn/tuev",
"slave-label": "master",
"working-dir": "subdir",
"job-setup": "export VAR=foobar"
}
}
The stages section contains an array of stages declarations that contain the following properties:
-
name
: the name of the stage -
jobs
: an array of job declarations with the following format:-
simple job declaration: name / command:
{"<jobname>": "<command>"}
-
extended job declaration:
{"<jobname>": {"cmd": "<command>", "<option1>": "<option1-value>", "<option2>": "option2-value"}, ... }
with the following options being available:
artifacts
: an array of strings with artifacts (files or directories) that should be passed to the next job. If the next job is a multi job, all sub-jobs will have the listed artifacts available. If several sub-jobs of a multi-job (see below) provide artifacts, the next job after the multi job will have all artifacts of all sub jobs available: in the example,job7
andjob8
(sub-jobs of a multi-job) will receive the artifactsspec3/
andspec4/
from sub-jobsjob4
andjob5
.upstream-jobs
: an array of strings with job names that should trigger this pipeline after they have a successful new builddownstream-jobs
: an array of strings with job names that should be triggered when this pipeline was built successfullytest-reports
: comma separated set of paths to junit test reports (wildcards like *.xml allowed)no-clean
: if set to true, the workspace will not be cleaned before starting the job (default is to always clear workspace -- us this if you would like to cache dependencies or build artifacts between builds)manual
(bool): if set to true, this job needs to be triggered manually by a user using the jenkins ui -- if omitted or set to false, job gets triggered automatically by its upstream jobslocalBranch
(bool): if set to true this job will check out to a local branch specified in settings-
multi job: an array of simple or extended job declarations (see
stage1 / job4 & job5
in example above). Those jobs will be executed in parallel:[<simple-job-decl>,<ext-job-decl>,<simple-job-decl>, ...]
-
-
next-stages
(optional): next stages to execute when this stage has been executed successfully
This section contains global settings for the pipeline:
jenkins-server
: base url to the jenkins servergit-url
: git url to the project that is to be builtgit-branch
: set this if you want to build a different branch to masterslave-label
(optional): only execute these jobs on jenkins slave with this labeljob-setup
(optional): before executing each job, execute the code provided heresilent
(optional): if set to true, don't send notification mails -- if omitted or false, sent mailsdefault-name
(optional): optionally, define how your pipeline should be named here; this property will be available onworking-dir
(optional): only consider the given subdir: only builds if the subdir contains changes; changes into the subdir before executing anything, i.e. all commands are relativ to the subdir, not the repository's root
This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.
Copyright (c) 2014 Daniel Bornkessel
See LICENSE for details.