NAV Navbar
Logo
YAML

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.4.0, which is intended for Bamboo version 6.4.0 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:

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:

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:

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:

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:

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.