Introduction
You are reading reference documentation for the Bamboo YAML Specs library. The Bamboo YAML Specs library allows you to define plan configuration in YAML and send it to Bamboo to have corresponding plans created or updated automatically. You can read more information about Bamboo Specs feature here.
Version information
This reference documentation is based on Bamboo Specs library version 6.6.2, which is intended for Bamboo version 6.6.2 and higher.
See older versions of documentation
Feedback
In case you found a bug, would like to suggest an improvement or just would like to share your impression about this documentation, please do not hesitate to report it our issue tracker.
Bamboo Specs Reference
Go back to Bamboo Specs reference
Let’s assume a hypothetical activity such as slaying dragons. This activity can be described as a build plan in Bamboo as follows:
Minimalistic definition
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
...
Plan can be created with single 10 lines only, you must specify at least those elements:
- project key in which plan will be created
- plan key
- plan name
- list of scripts to execute
Job requirements
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
requirements:
- isDragonLazy
- isDragonAsleep
- isCaveDeep
...
It’s not uncommon to run the same build on different platforms, such as operating systems or databases. It’s also not uncommon to run many times with even the same set of tools but with different versions to check the compatibility matrix. In such cases defining proper requirements for a build agent is necessary.
A requirement specifies a capability that an agent must have for it to build that job.
There are four types of capabilities in Bamboo that can be specified by job requirements:
- Executable capabilities define external programs that can be called by Bamboo, for example Ant, Maven, MSBuild or PHPUnit.
- JDK capabilities define the JDK versions to be used by the job or task.
- Custom capabilities can be used to control which jobs will be built by a particular agent. For example, if the
builds for a particular job should only run in a Windows environment, you could create a custom capability of
operating.system.Windows
for the appropriate agent(s), and specify it as a requirement for this job.
To learn more, refer to the following documentation pages:
Additionally, in Bamboo variables documentation you may find details on how to refer to various types of capabilities.
Implicit match type for requirements is Exists.
Job artifacts
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
artifacts:
- name: Blue dragon's head
path: dragon/blue/head
- name: Blue dragon's claw
path: dragon/blue/claw
...
Artifacts are files created by a job build (e.g. JAR files). Artifact definitions are used to specify which artifacts to keep from a build and are configured for individual jobs. Artifacts are implicitly shared between jobs or stages in a plan. Shared artifacts can be also used by different plans or deployment projects. For plans created with YAML Specs artifacts are implicitly downloaded in a subsequent stages.
Test parsers
Minimalistic definition
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
testParsers:
- testng
- mocha
...
Simple definition
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
testParsers:
- type: testng
testResults: '**/testng/*.xml'
- type: mocha
testResults: 'report.json'
...
Full definition
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
testParsers:
- type: mocha
testResults:
- report.json
- type: junit
testResults:
- '**/test-reports/*.xml'
- '**/custom-test-reports/*.xml'
...
Test tasks in Bamboo parse test data, produced by a particular testing framework, which allows to visalise test results on Bamboo Tests tab in the UI. You can use one of three ways of defining test parsers for a job:
- minimalistic -> define only type of your parser. Location of test reports will be provided for you by default
- simple -> define parser type and ant glob where to find test reports
- full -> define parser type and list of places where to look for test reports, both ant globs are legal
Test parser | Default reports location |
---|---|
JUnit | **/test-reports/*.xml |
NUnit | **/test-reports/*.xml |
TestNG | **/testng-results.xml |
Mocha | mocha.json |
Scripts interpreter
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- '#!/bin/bash'
- echo 'Going to kill the red dragon, in bash'
interpreter: shell
- jobs:
- scripts:
- echo 'Going to kill the red dragon, in powershell'
interpreter: powershell
- jobs:
- scripts:
- echo 'Going to kill the red dragon, in cmd.exe'
interpreter: cmd.exe
...
YAML Specs execute script tasks. You can specify which interpreter to use.
Script Interpreter | Description |
---|---|
/bin/sh | script will be run by /bin/sh |
cmd.exe or cmd | script will be run by cmd.exe |
Powershell | script will be run by Windows PowerShell |
Shell | script will be run by an interpreter chosen based on the shebang line of the script |
Multiple jobs
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
- sleep 1
- echo 'Nailed it'
- scripts:
- echo 'Going to slay the blue dragon, you just watch'
- sleep 1
- echo 'Piece of cake'
...
A Bamboo job is a single build unit within a plan. One or more jobs can be organized into one or more stages. The jobs in a stage can all be run at the same time, if enough Bamboo agents are available.
A job created by YAML Specs:
- Checks out origin repository and processes a series of one or more scripts and test parser tasks that are run sequentially on the same agent.
- Defines the artifacts that the build will produce. Artifacts are implicitly shared, which means those can be downloaded by other stages, plans and deployment projects.
- Uses artifacts produced in a previous stages.
- Each plan should contain at least one job.
Multiple stages
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
artifacts:
- name: Blue dragon's head
path: dragon/blue/head
- name: Blue dragon's claw
path: dragon/blue/claw
- jobs:
- scripts:
- echo 'I am here to claim my reward'
...
Stages group (or ‘map’) jobs to individual steps within a plan’s build process. For example, you may have an overall plan build process that comprises a compilation step, followed by several test steps, followed by a deployment step. You can create separate Bamboo stages to represent each of these steps.
A stage:
- Shall have at least one job
- Processes its jobs in parallel, on multiple agents (where available).
- Must successfully complete all its jobs before the next stage in the plan can be processed.
- May produce artifacts that will be downloaded for use by a subsequent stage.
- Each plan should contain at least one stage.
Complex plan
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- echo 'Going to kill the red dragon, watch me'
- sleep 1
- echo 'Nailed it'
requirements:
- isDragonLazy
artifacts:
- name: Red dragon's head
path: dragon/red/head
- scripts:
- echo 'Going to slay the blue dragon, you just watch'
- sleep 1
- echo 'Piece of cake'
requirements:
- isDragonAsleep
- isCaveDeep
artifacts:
- name: Blue dragon's head
path: dragon/blue/head
- name: Blue dragon's claw
path: dragon/blue/claw
- jobs:
- scripts:
- echo 'I am here to claim my reward'
- sleep 1
- echo 'Thank you, your highness'
requirements:
- isKingPresent
artifacts:
- name: Gold coins
path: pocket/money
- name: Medal of courage
path: pocket/medal
...
A plan created with YAML Specs can mix all of the features mentioned within this documentation, therefore plan definition may be more complex and allow for more sophisticated use cases.
Docker
Enable Docker for a whole plan.
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
dockerImage: postgres
stages:
- jobs:
- scripts:
- echo 'Job 1'
- scripts:
- echo 'Job 2'
...
Enable Docker for a single job.
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- dockerImage: postgres
scripts:
- echo 'Job 1'
- scripts:
- echo 'Job 2'
...
Enable Docker for a whole plan definition and override it for a single job.
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
dockerImage: postgres
stages:
- jobs:
- scripts:
- echo 'Job 1'
- dockerImage: mysql
scripts:
- echo 'Job 2'
...
Builds are normally run on the Bamboo agent’s native operating system. However, jobs can be instrumented to be run in a Docker container, for better control over the available tool set and additional build isolation.
To run a job in a Docker container, you’ll need to specify which Docker image to use. You can specify Docker image for
an entire plan and for each individual job. If a Docker image is specified both for a job and for a plan, the job’s
configuration takes precedence. You can choose the repository host, namespace and tag for the image, by following
the standard Docker image format, for example localhost:5000/namespace/image:tag
.
Bamboo variables are allowed in the Docker
image configuration field.
See the examples on how to set up Docker configuration.
Java
With Maven
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- M2_HOME=${bamboo_capability_system_builder_mvn3_Maven_3}
- ${bamboo_capability_system_builder_mvn3_Maven_3}/bin/mvn clean install
requirements:
- system.builder.mvn3.Maven 3
- linux
artifacts:
- name: library
path: target/*.jar
testParsers:
- junit
...
With Gradle
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- ./gradlew clean build
requirements:
- java
- linux
artifacts:
- name: library
path: target/*.jar
testParsers:
- junit
...
Use this template as a starting point to create plan definition to build and test Java projects. Just copy it and paste to bamboo-specs/bamboo.yaml file in your repository.
Python
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- ${bamboo_capability_system_builder_pip} install -r requirements.txt
- ${bamboo_capability_system_builder_python} script.py
requirements:
- python
- linux
artifacts:
- name: csv_report
path: output/*.csv
...
Use this template as a starting point to create plan definition to build and test Python projects. Just copy it and paste to bamboo-specs/bamboo.yaml file in your repository.
Node
---
project:
key: DRAGON
plan:
key: SLAYER
name: Dragon Slayer Quest
stages:
- jobs:
- scripts:
- ${bamboo_capability_system_builder_npm} install
- ${bamboo_capability_system_builder_npm} test
requirements:
- node
- linux
testParsers:
- mocha
...
Use this template as a starting point to create plan definition to build and test Node projects. Just copy it and paste to bamboo-specs/bamboo.yaml file in your repository.