Plan DSL for Bamboo
API Reference

Plan DSL for Bamboo API reference

Welcome to the Plan DSL for Bamboo API reference! In the following sections you can find the structure and building elements of the Groovy-based DSL and YAML syntax which allows you to manage your Bamboo build plans and deployment projects as code.

The project is hosted on GitHub. You can find more information about the setup of the plug-in, real-world use cases and advanced concepts in the Wiki.

Feedback

Please feel free to contact us if you have any questions or support requests: Drop us an email or create an issue on Github.

Contribution

We have a lot of areas where you can contribute to. Especially, DSL support for more Bamboo tasks is required. Please see the contribution guide for more information. We appreciate your support!

Project

A project contains of a collection of plans. Each project has a key (which must consist of an uppercase letter followed by one or more uppercase alphanumeric characters), a name and its build plans. Since Bamboo 6.2, it can also have project permissions and plan inheritance permissions for users and groups.

project(key: 'PROJECTKEY', name: 'my project') {
    plan(key: 'PLAN1KEY', name: 'my plan 1') {
    }
    plan(key: 'PLAN2KEY', name: 'my plan 2') {
    }
    projectPermissions {
    }   
    planPermissions {
    }
}

project:
  key: PROJECTKEY
  name: my project
  plans:
    - key: PLAN1KEY
      name: my plan 1
    - key: PLAN2KEY
      name: my plan 2
  projectPermissions:   
  planPermissions:

Project Permissions

Project permissions allow you to control access to project permissions and settings.

project(key: 'PROJECTKEY', name: 'my project') {
    projectPermissions {
        user(name: 'diego') {
            permissionTypes PermissionType.CREATE, PermissionType.ADMIN
        }
        group(name: 'devops') {
            permissionTypes PermissionType.CREATE
        }
        other(type: OtherUserType.LOGGED_IN_USERS) {
            permissionTypes PermissionType.CREATE
        }
    }   
}

project:
  key: PROJECTKEY
  name: my project
  projectPermissions:
    user:
      diego:
        - !permission ADMIN
        - !permission CREATE        
    group:
      devops: !permission CREATE
    other:
      !userType LOGGED_IN_USERS: !permission CREATE

Plan Permissions

Build plan permissions allow a user to control access to the functions of the build plan. These include viewing, editing, building, cloning and administering a build plan.

project(key: 'PROJECTKEY', name: 'my project') {
    planPermissions {
        user(name: 'paul') {
            permissionTypes PermissionType.ADMIN
        }
        group(name: 'mgmt') {
            permissionTypes PermissionType.EDIT
        }
        other(type: OtherUserType.LOGGED_IN_USERS) {
            permissionTypes PermissionType.ADMIN, PermissionType.EDIT
        }
        other(type: OtherUserType.ANONYMOUS_USERS) {
            permissionTypes PermissionType.VIEW
        }
    }
}

project:
  key: PROJECTKEY
  name: my project
  planPermissions:
    user:
      paul: !permission ADMIN
    group:
      mgmt: !permission EDIT
    other:
      !userType LOGGED_IN_USERS:
        - !permission ADMIN        
        - !permission EDIT     
      !userType ANONYMOUS_USERS:  !permission VIEW

Plans

A plan contains everything related to a build plan in Bamboo. It consists of multiple stages, SCM information, triggers, plan branches, notifications, build variables, dependencies, miscellaneous options and deployment projects. Note that you only need to specify the elements you really need.

Also note that the key of the plan must consist of an uppercase letter followed by one or more uppercase alphanumeric characters.

project(key: 'PROJECTKEY', name: 'my project') {
    plan(key: 'PLAN1KEY', name: 'my plan 1') {
        description 'description for plan'
        enabled true

        stage(name: 'package') {
        }
        stage(name: 'test') {
        }
        scm {
        }
        triggers {
        }
        branches {
        }
        notifications {
        }
        dependencies {
        }
        variables {
        }
        miscellaneous {
        }
        permissions {
        }
        deploymentProject(name: 'staging') {
        }
        deploymentProject(name: 'production') {
        }
    }
}

project:
  key: PROJECTKEY
  name: my project
  plans:
    - key: PLAN1KEY
      name: my plan 1
      stages:
        - name: package
        - name: test
      scm:          
      triggers:
      branches:
      notifications:
      dependencies:
      variables:
      miscellaneous:
      permissions:
      deploymentProjects:
        - name: staging
        - name: production

Dependencies

Specifies the dependencies for this plan. When the current plan builds successfully, it will trigger the child plans to build.

plan(key: 'SIMPLEPLAN', name: 'Simple plan') {
    dependencies {
        blockingStrategy DependencyBlockingStrategy.BLOCK_BUILD_IF_PARENT_BUILDS_ARE_QUEUED
        advancedOptions {
            triggerDependenciesOnlyWhenAllStagesHaveRunSuccessfully true
            autoDependencyManagement true
            enableDependenciesForAllBranches false
        }
        childPlans 'HELLO-HELLO', 'SEED-SEED'
    }
}

plans:
  - key: SIMPLEPLAN
    name: Simple plan
    dependencies:
      blockingStrategy: !dependencyBlocking BLOCK_BUILD_IF_PARENT_BUILDS_ARE_QUEUED
      advancedOptions:
        enableDependenciesForAllBranches: true
        triggerDependenciesOnlyWhenAllStagesHaveRunSuccessfully: true
        autoDependencyManagement: false
      dependencies:
        - planKey: HELLO-HELLO
        - planKey: SEED-SEED

Miscellaneous

Specifies the miscellaneous options for this plan.

plan(key: 'SIMPLEPLAN', name: 'Simple plan') {
    miscellaneous {
        expire {
            expireBuildResults true
            expireBuildArtifacts false
            expireBuildLogs true
            expireAfter 10, TimeUnit.WEEKS
            minimumBuildsToKeep 12
            keepBuildsWithTheFollowingLabels 'DONOTDELETE', 'IMPORTANT'
        }

        configure(
            'custom.ruby-config-runtime': 'SYSTEM 2.0.0-p648@default',
            'custom.ruby-config-environmentVariables': 'SOME_VAR="-D123 -R345"'
        )
    }
}

plans:
  - key: SIMPLEPLAN
    name: Simple plan
    miscellaneous:
        expirationDetails:
          keepBuildsWithLabels:
            - DONOTDELETE
            - IMPORTANT
          expireAfter: 10
          expireTimeUnit: !timeUnit WEEKS
          minimumBuildsToKeep: 12
          expireBuildResults: true
          expireBuildArtifacts: false
          expireBuildLogs: true
          customSettings:
            custom.ruby-config-runtime: SYSTEM 2.0.0-p648@default
            custom.ruby-config-environmentVariables: SOME_VAR="-D123 -R345"

Plan branches

The plan branches section both configures how you would like to work with plan branches as well as contains the individual plan branch configurations.

plan(key: 'PLAN1KEY', name: 'my plan 1') {
    branches {
        autoBranchManagement {
        }
        merging {
        }
        notifications(Branch.NotifyOnNewBranchesType.USE_PLANS_NOTIFICATION_SETTINGS)
        triggers(NewPlanBranchesTriggerType.RUN_NEW_PLAN_BRANCHES_MANUALLY)
        branch(name: 'develop') {
        }
        branch(name: 'feature_ui_improvements') {
            vcsBranchName 'feature/ui_improvements'
        }
    }
}    

plans:
  - key: PLAN1KEY
    name: my plan 1
    branches:
      autoBranchManagement:
      merging:
      notifications: !notifyOnNewBranchesType USE_PLANS_NOTIFICATION_SETTINGS
      triggers: !newPlanBranchesTriggerType RUN_NEW_PLAN_BRANCHES_MANUALLY
      branches:
        - name: develop
        - name: feature_ui_improvements
          vcsBranchName: feature/ui_improvements

Auto Branch Management

Plan branches can be created and deleted automatically based on branch creation and deletion settings for the primary source repository. This can be configured inside the auth branch management section.

branches {
    autoBranchManagement {
        createPlanBranchesForNewPullRequests()
        deletePlanBranchesAfterDays 7
        deleteInactivePlanBranchesAfterDays 14
    }
}

branches:
  autoBranchManagement:
    newBranchesStrategy: !newBranches NEW_PLAN_BRANCHES_FOR_PULL_REQUESTS
    deletedBranchesStrategy: !deletedBranches DELETE_PLAN_BRANCHES_AFTER_DAYS
    deletePlanBranchesAfterDays: 7
    inactiveBranchesStrategy: !inactiveBranches DELETE_INACTIVE_PLAN_BRANCHES_AFTER_DAYS
    deleteInactivePlanBranchesAfterDays: 14

Merging

Automatic merging can test the merge between branches and push changes back to the repository on a successful build. This setting will be applied to all new plan branches.

branches {
    merging {
        gateKeeper {
            checkoutBranch 'SIMPLEPROJECT-SIMPLEPLAN'
            pushEnabled true
        }
        // OR:
        branchUpdater {
            mergeFromBranch 'SIMPLEPROJECT2-SIMPLEPLAN0'
            pushEnabled false
        }
    }
}

branches:
  merging:
    mergeStrategy: !gateKeeper
      planBranchKey: PLANKEY
      pushEnabled: true 
    # OR:
    mergeStrategy: !branchUpdater
      planBranchKey: PLANKEY
      pushEnabled: false

Notifications

These notification preferences are applied to all new plan branches.

branches {
    notifications(Branch.NotifyOnNewBranchesType.DO_NOT_SEND_NOTIFICATIONS)
}

branches:
  notifications: !notifyOnNewBranchesType DO_NOT_SEND_NOTIFICATIONS

Triggers

Branch specific triggers

This defines how new plan branches should be triggered.

branches {
    triggers(NewPlanBranchesTriggerType.RUN_NEW_PLAN_BRANCHES_MANUALLY)
}

branches:
  triggers: !newPlanBranchesTriggerType RUN_NEW_PLAN_BRANCHES_MANUALLY

Branch settings

Branch specific settings

This configures the setting for a specific plan branch. A plan branch can have triggers, merging settings, build variables and notification settings.

branches {
    branch(name: 'feature_ui_improvements') {
        vcsBranchName 'feature/ui_improvements'
        description 'my feature branch'
        enabled true
        cleanupAutomatically true

        triggers {
            scheduled {
                cron('* * * * * * *')
                    onlyRunIfOtherPlansArePassing {
                    planKeys 'SEED-SEED-JOB1'
                }
            }
        }
        merging {
            branchUpdater {
                mergeFromBranch 'SIMPLEPROJECT2-SIMPLEPLAN0'
                pushEnabled false
            }
        }
        variables {
            variable 'name', 'value'
        }
        notifications(NotifyOnNewBranchesType.USE_PLANS_NOTIFICATION_SETTINGS)
    }
}  

branches:
  - name: feature_ui_improvements
    vcsBranchName: feature/ui_improvements
    description: my feature branch
    enabled: true
    cleanupAutomatically: true
    triggers:
      - !scheduled
        cronExpression: * * * * * * *
        onlyRunIfOtherPlansArePassing:
          planKeys: [SEED-SEED-JOB1]
    merging:
      mergeStrategy: !branchUpdater
        planBranchKey: 'SIMPLEPROJECT2-SIMPLEPLAN0'
        pushEnabled: false
    variables:
      - key: name
        value: value 
    notifications: !notifyOnNewBranchesType USE_PLANS_NOTIFICATION_SETTINGS

Stage

A stage consists of a name, a description, a manual field (should the stage run automatically or not) and multiple jobs.

plan(key: 'PLAN1KEY', name: 'my plan 1') {
    stage(name: 'package') {
        description 'packages the software'
        manual false

        job(key: 'TEST', name: 'tests the software') {
        }
        // more jobs...
    }
}

plans:
  - key: PLAN1KEY
    name: my plan 1
    stages:
      - name: mystage
        description: packages the software
        manual: false
        jobs:
          - key: TEST
            name: tests the software

Jobs

A build job has a key, a name, a description, an enabled flag, a list of tasks, artifacts, requirements and miscellaneous options.

stage(name: 'package') {
    job(key: 'TEST', name: 'Tests the software') {
        description 'This is the job description'
        enabled true
        tasks {
        }
        artifacts {
        }
        requirements {
        }   
        miscellaneous {
        }
    }
}

stages:
  - name: package
    jobs:
      - key: TEST
        name: Tests the software
        description: This is the job description
        enabled: true
        tasks:
        artifactDependencies:
        artifactDefinitions:
        requirements:
        miscellaneous:

Artifacts

Defines the artifact(s) for this job.

job(key: 'BUILD', name: 'Builds the software') {
    artifacts {
        definition(name: 'my JAR', copyPattern: '**/*.jar') {
            location 'target'
            shared true
        }
        // more artifact definitions
    }
}

jobs:
  - key: DEPLOY
    name: Deploys the software
    artifactDefinitions:
      - name: my JAR
        copyPattern: '**/*.jar'
        location: target
        isShared: true
      #  more artifact definitions

Artifact Dependencies

Defines the artifact dependencies for this job.

job(key: 'DEPLOY', name: 'Deploys the software') {
    artifacts {
        dependency(name: 'my JAR') {
            destinationDirectory 'deploy'
        }
    }
}

jobs:
  - key: DEPLOY
    name: Deploys the software
    artifactDependencies:
      - name: my JAR
        destinationDirectory: deploy

Requirements

Defines the requirements for this job.

job(key: 'PACKAGE', name: 'Packages the software') {
    requirements {
        requirement(capabilityKey: 'system.builder.mvn3.maven323',
                    matchType: matches('[A-Z0-9]*')) {
        }
        requirement(capabilityKey: 'system.builder.msbuild.MSBuild v4.0 (64bit)',
                    matchType: exists()) {
        }
    }
}

jobs:
  - key: PACKAGE
    name: Packages the software
    requirements:
      - capabilityKey: system.builder.mvn3.maven323
        matchType: !matches
          matchValue: '[A-Z0-9]*'
      - capabilityKey: system.builder.msbuild.MSBuild v4.0 (64bit)
        matchType: !exists

Miscellaneous

Defines the miscellaneous options for this job. Here you can configure the build hung options, NCover and Clover settings.

job(key: 'TEST', name: 'Tests the software') {
    miscellaneous {
        cleanWorkingDirectoryAfterEachBuild()
        overrideDefaultHangingBuildDetectionCriteria {
            buildTimeMultiplier 2.5
            logQuietTimeInMinutes 10
            buildQueueTimeoutInMinutes 60
        }
        nCoverOutputWillBeProduced {
            nCoverXmlDirectory 'a/b/c'
        }
        cloverCodeCoverage {
            automaticallyIntegrateCloverIntoBuild(cloverLicense: 'LICENSE') {
                generateCloverHistoricalReport()
                generateJSONReport()
            }
        } 
        patternMatchLabelling {
            regexPattern '[a-z]+'
            labels 'test'
        }
        configure(
            'custom.xxx.list': 'test',
            'custom.xxx.filename': 'test.groovy'
        )
    }
}

jobs:
  - key: PACKAGE
    name: Packages the software
    miscellaneous:
      cleanWorkingDirectoryAfterEachBuild: true
      buildHungOptions:
        buildTimeMultiplier: 2.5
        logQuietTimeInMinutes: 10
        buildQueueTimeoutInMinutes: 60
      nCoverOutput:
        nCoverXmlDirectory: a/b/c
      cloverCodeCoverage:
        cloverLicense: 'LICENSE'
        cloverOptions:
          generateCloverHistoricalReport: true
          generateJSONReport: false
        integrationOptions: !integration AUTOMATICALLY_INTEGRATE_CLOVER_INTO_BUILD
      patternMatchLabelling:
        regexPattern: [a-z]+
        labels: test
      customSettings:
        custom.xxx.list: test
        custom.xxx.filename: test.groovy

Tasks

Defines the task(s) for this build job or deployment project environment.

The DSL supports the following built-in tasks:

For other tasks not listed here, please see custom tasks on how to use them.

job(key: 'PACKAGE', name: 'Packages the software') {
    tasks {
        // your tasks
    }
}

jobs:
 - key: PACKAGE
   name: Packages the software
   tasks:
     # your tasks

Script

A simple script task.

tasks {
    script() {
        description 'my task'
        inline {
            interpreter: !scriptInterpreter LEGACY_SH_BAT
            scriptBody 'echo "Hello World"'
        }
    }
}

tasks:
  - !script
    description my task
    inlineScript:
      interpreter: !scriptInterpreter LEGACY_SH_BAT
      scriptBody: echo "Hello World"

Command

A task to execute a command.

tasks {
    command() {
        description 'my command'
        enabled true
        isFinal true
        workingSubDirectory 'mydir'
        argument '-n'
        environmentVariables 'what=EVER'
        executable 'atlas-clean'
    }
}

tasks:
  - !command
    description: my command
    enabled: true
    isFinal: true
    workingSubDirectory: mydir
    argument: -n
    environmentVariables: what=EVER
    executable: atlas-clean

Inject Bamboo Variables

A task to inject Bamboo variables from a file with a simple “key=value” format.

tasks {
    injectBambooVariables(propertiesFilePath: 'envVars.properties', namespace: 'soulmv') {
        description 'Inject Build Variables'
        isFinal true
        variablesScope VariablesScope.RESULT
    }
}

tasks:
  - !injectBambooVariables
    propertiesFilePath: path/to/props.txt
    namespace: myNs
    variablesScope: !variablesScope RESULT

Checkout

A task to checkout a repository to a working directoy.

tasks {
    checkout() {
        description 'checkout repo'
        forceCleanBuild true

        repository(name: 'Bamboo Plan DSL') {
            checkoutDirectory 'src'
        }
    }
}

tasks:
  - !checkout
    description: checkout repo
    forceCleanBuild: true
    repositories:
      - name: Bamboo Plan DSL
        checkoutDirectory: src

Clean Working Directory

A task to clean the working directory of a build job.

tasks {
    cleanWorkingDirectory() {
        description 'Clean the working directory'
    }
}

tasks:
  - !cleanWorkingDir
    isFinal: true

Artifact Download

A task to copy a Bamboo shared artifact to an agent working directory.

tasks {
    artifactDownload() {
        description 'Download release content'
        artifact(name: 'my JAR2') {
            destinationPath 'doc'
            sourcePlanKey 'MYPLAN'
        }
    }
}

tasks:
  - !artifactDownload
    description Download release content
    artifacts:
    - name: my JAR2
      destinationPath: doc
      sourcePlanKey: MYPLAN

Deploy plug-in

Deploys an Atlassian plugin to a remote application server. This task is provided by the Continuous Plugin Deployment for Bamboo plug-in.

tasks {
    deployPlugin(
        productType: ch.mibex.bamboo.plandsl.dsl.tasks.DeployPluginTask.ProductType.STASH,
        deployUsername: "admin",
        deployURL: "http://myserver",
        deployArtifactName: "Plan DSL",
        deployPasswordVariable: '${bamboo.bitbucket_server_password}'
    ) {
        description "Deploy plug-in to staging server"
        enabled true
        deployBranchEnabled true
        certificateCheckDisabled true
        useAtlassianIdWebSudo false
    }
}

tasks:
  - !deployPlugin
    productType: !productType STASH
    deployUsername: admin
    deployURL: http://myserver
    deployArtifactName: Plan DSL
    deployPasswordVariable: !env bitbucket_server_password
    description: Deploy plug-in to staging server
    enabled: true
    deployBranchEnabled: true
    certificateCheckDisabled: false
    useAtlassianIdWebSudo: false

ShipIt to Marketplace

Deploys your plug-ins to the Atlassian Marketplace. This task is provided by the ShipIt to Marketplace for Bamboo plug-in.

tasks {
    shipIt2marketplace(deployArtifactName: 'Plan DSL') {
        description 'ship it to the Atlassian Marketplace'
        enabled true
        isFinal false
        onlyAllowToTriggerFromJira true
        runOnBranchBuilds false
        publicVersion true
        deduceBuildNrFromPluginVersion true
        bambooUserId 'admin'
        jqlToCollectReleaseNotes 'status in (resolved,closed,done)'
    }
}

tasks:
  - !shipit2marketplace
    deployArtifactName: Plan DSL
    description: ship it to the Atlassian Marketplace
    enabled: true
    isFinal: false
    onlyAllowToTriggerFromJira: true
    runOnBranchBuilds: false
    publicVersion: true
    deduceBuildNrFromPluginVersion: true
    bambooUserId: admin
    jqlToCollectReleaseNotes: status in (resolved,closed,done)

Maven 3.x

A task to execute one or more Maven 3 goals as part of a build.

tasks {
    maven3x(goal: 'install') {
        description 'build plug-in'
        workingSubDirectory '.'
        executable 'maven323'
        buildJdk 'jdk8'
        environmentVariables 'what=EVER'
        withTests {
            testResultsDirectory 'tests/'
        }
        useMavenReturnCode false
        projectFile 'a/b'
    }
}

tasks:
  - !maven3x
    goal: install
    description: build plug-in
    workingSubDirectory: .
    executable: maven323
    buildJdk: jdk8
    environmentVariables: what=EVER
    withTests:
      testResultsDirectory: tests/
    projectFile: a/b
    useMavenReturnCode: false

NodeJS

A task to execute JavaScript on the server with Node.js.

tasks {
    nodeJs(executable: '/usr/bin/nodejs', script: 'package.json') {
        description 'execute Node'
        workingSubDirectory '.'
        arguments '-n'
        environmentVariables 'what=EVER'
    }
}

tasks:
  - !nodeJs
    executable: /usr/bin/nodejs
    script: package.json
    description: execute Node
    workingSubDirectory: .
    arguments: -n
    environmentVariables: what=EVER

NPM

A task to use the NPM package manager for Node.js.

tasks {
    npm(executable: '/usr/bin/nodejs', command: 'install') {
        description 'execute NPM'
        workingSubDirectory '.'
        useIsolatedCache true
        environmentVariables 'what=EVER'
    }
}

nodes:
  - !npm
    executable: /usr/bin/nodejs
    command: install
    workingSubDirectory: .
    useIsolatedCache: true
    environmentVariables: what=EVER

MSBuild

A task to run MSBuild as part of a build.

tasks {
    msbuild(executable: 'msbuild', projectFile: 'MySolution.sln') {
        description 'run MSBuild'
        workingSubDirectory '.'
        environmentVariables 'what=EVER'
        options '/d'
    }
}

tasks:
  - !msbuild
    executable: msbuild
    projectFile: MySolution.sln
    description: run MSBuild
    workingSubDirectory: .
    environmentVariables: what=EVER
    options: /d

JUnit Parser

A task to parse and display JUnit test results.

tasks {
    junitParser {
        description 'parse test results'
        testResultsDirectory 'test-reports/'
        pickUpTestResultsCreatedOutsideOfBuild()
    }
}

tasks:
  - !junitParser
    description parse test results
    testResultsDirectory: test-reports/
    pickUpTestResultsCreatedOutsideOfBuild: true

SCP

A task to copy files to a remote server using SCP.

tasks {
    scp(host: 'localhost', userName: 'bob') {
        description 'Ship it to remote server'
        passwordAuth {
            password env('MY_PASSWORD_VARIABLE')
        }
        artifactByLocalPath(localPath: '*.zip,*.jar') {
            useAntPatternsToSelectFiles()
        }
        remotePath 'a/b'
        advancedOptions {
            hostFingerprint 'test'
            port 22
        }
    }
}

tasks:
  - !scp
    host: localhost
    userName: bob
    description: Ship it to remote server
    authType: !passwordAuth
        password: !env MY_PASSWORD_VARIABLE
    localPath: '*.zip,*.jar'
    artifactLocalPath:
      useAntPatternsToSelectFiles: true
    remotePath: a/b
    advancedOptions:
      hostFingerprint: test
      port: 22

SSH

A task to run a remote command over SSH.

tasks {
    ssh(host: 'localhost', userName: 'bob') {
        description 'show dir on remote server'
        keyWithoutPassphrase {
            privateKey env('MY_PRIVATE_KEY')
            enableSshCompression()
        }
        command 'ls -l'
        advancedOptions {
            hostFingerprint 'test'
            port 22
        }
    }
}

tasks:
  - !ssh
    host: localhost
    userName: bob
    description: show dir on remote server
    authType: !sshWithoutPassphraseAuth
      privateKey: !env MY_PRIVATE_KEY
      enableSshCompression: true
    command: ls -l
    advancedOptions:
      hostFingerprint: test
      port: 22

Docker

A task to build, run and deploy Docker containers using the Docker command line interface.

tasks {
    docker(repository: 'registry.address:port/namespace/repository:tag') {
        description 'build docker image'
        command DockerCommand.BUILD
        dockerfileContents 'FROM debian:jessie-slim'
        useAnExistingDockerfile()
        workingSubDirectory '.'
        environmentVariables 'what=EVER'
        saveTheImageAsFile 'image.iso'
        doNotUseCachingWhenBuildingImage true
    }
}

tasks:
  - !docker
    repository: registry.address:port/namespace/repository:tag
    description: build docker imag
    command: !dockerCommand BUILD
    existingDockerfile: true
    dockerfileContents: FROM debian:jessie-slim
    workingSubDirectory: .
    environmentVariables: what=EVER
    saveTheImageAsFile: image.iso
    doNotUseCachingWhenBuildingImage: false

Heroku deploy WAR

A task to deploy a WAR artifact to Heroku.

tasks {
    herokuDeployWar(apiKey: 'key', appName: 'myapp', warFile: 'my.war') {
        enabled true
        description "Deploy WAR to Heroku"
    }
}

tasks:
  - !herokuDeployWar
    apiKey: key
    appName: myapp
    warFile: my.war
    enabled: true
    description: Deploy WAR to Heroku

Custom tasks

There exist dozens of community-provided Bamboo tasks in the Atlassian Marketplace where the plug-in does not provide special syntax for. This does not mean that these tasks cannot be used in the plug-in. The plug-in offers a standard way to use and configure any task with the custom task syntax. See the example here for the Sonar for Bamboo Maven Task.

As you can see, there are default attributes (description and enabled) any task has and there is a configure block with the task-specific fields. You probably ask yourself how you can get the plug-in task key (ch.mibex.bamboo.sonar4bamboo:sonar4bamboo.maven3task) and the field names (like sonarJavaSource).

The way to retrieve these values is to add the Bamboo task you want to use to your build job, configure it as you would like to have it, and then save the configuration form while watching the POST request in your browser’s dev tools. Please consult the Wiki for more information.

tasks {
    custom(pluginKey: 'ch.mibex.bamboo.sonar4bamboo:sonar4bamboo.maven3task') {
        description 'Analyze with SonarQube'
        configure(
              chosenSonarConfigId: 1,
              useGradleWrapper: false,
              failBuildForSonarErrors: true,
              failBuildForBrokenQualityGates: false,
              executable: 'mvn3',
              illegalBranchCharsReplacement: '_',
              useNewGradleSonarQubePlugin: false,
              sonarJavaTarget: '1.8',
              sonarJavaSource: '1.8',
              environmentVariables: 'JAVA_OPTS="-Xms128m -Xmx1024m"',
              replaceSpecialBranchChars: false,
              buildJdk: 'JDK 1.5',
              additionalProperties: '-sonar.branch="master"',
              autoBranch: true,
              useGlobalSonarServerConfig: true,
              workingSubDirectory: 'src'
        )
    }
}

tasks:
  - !customTask
    pluginKey: ch.mibex.bamboo.sonar4bamboo:sonar4bamboo.maven3task
    description: Analyze with SonarQube
    taskConfig:
      chosenSonarConfigId: 1
      useGradleWrapper: false
      failBuildForSonarErrors: true
      failBuildForBrokenQualityGates: false
      executable: mvn3
      illegalBranchCharsReplacement: _
      useNewGradleSonarQubePlugin: false
      sonarJavaTarget: 1.8
      sonarJavaSource: 1.8
      environmentVariables: JAVA_OPTS="-Xms128m -Xmx1024m"
      replaceSpecialBranchChars: false
      buildJdk: JDK 1.5
      additionalProperties: -sonar.branch="master"
      autoBranch: true
      useGlobalSonarServerConfig: true
      workingSubDirectory: src

SCM overview

SCM is a collection of repository definition(s) for a plan or plan branch. The first repository in the list is automatically the default one.

The DSL supports the following repository types:

Custom repositories allow you to support repositories which are not built-in into Bamboo, but are instead provided by a plug-in (e.g., the TFS repository type).

plan(key: 'PLAN1KEY', name: 'my plan 1') {
    scm {
        // repository definitions
    }
}

plans:
  - key: PLAN1KEY
    name: my plan 1
    scm:
      # repository definitions

Bitbucket Cloud

A definition for Bitbucket Cloud repositories.

scm {
    bitbucketCloud(name: 'myBitbucketGitRepo') {
        git { 
            advancedOptions {
                useShallowClones true
                useSubmodules true
                commandTimeoutInMinutes 20
                verboseLogs true
                fetchWholeRepository true
                quietPeriod {
                    waitTimeInSeconds 120
                    maximumRetries 3
                }
                includeExcludeFiles(MatchType.EXCLUDE_ALL_MATCHING_CHANGES) {
                    filePattern 'exe'
                }
                excludeChangesetsRegex 'FIXES .*'
                webRepository {
                    fisheye {
                        url 'http://localhost:7990'
                        repositoryPath 'a/b/c'
                        repositoryName 'd'
                    }
                }
            }
        }
        repoSlug 'project_1/java-maven-simple'
        branch 'develop'
        passwordAuth {
            userName 'admin'
            password 'pw'
        }
    }
}

scm:
  - !bitbucketCloud
    name: myBitbucketGitRepo
    advancedOptions:
      useShallowClones: true
      useSubmodules: false
      commandTimeoutInMinutes: 20
      verboseLogs: true
      fetchWholeRepository: false
      quietPeriod:
        waitTimeInSeconds: 120
        maximumRetries: 3
      includeExcludeFiles:
        matchType: !matchType EXCLUDE_ALL_MATCHING_CHANGES
        filePattern: exe
      excludeChangesetsRegex: 'FIXES .*'
      webRepository:
        type: !fisheyeWeb
          url: http://localhost:7990
          repositoryPath: a/b/c
          repositoryName: d
      repoSlug: project_1/java-maven-simple
      branch: develop
      authType: !password
        userName: admin
        password: pw

Bitbucket Server

A definition for Bitbucket Server repositories.

scm {
    bitbucketServer(name: 'myBitbucketServerRepo') {
        projectKey 'project_1'
        repoSlug 'rep_1'
        branch 'develop'
        serverName 'bitbucketServer'
        repositoryUrl 'ssh://git@localhost:7999/project_1/rep_1.git'

        advancedOptions {
            enableRepositoryCachingOnRemoteAgents true
            useShallowClones true
            useSubmodules true
            commandTimeoutInMinutes 20
            verboseLogs true
            fetchWholeRepository true
            enableLfsSupport true
            quietPeriod {
                waitTimeInSeconds 10
                maximumRetries 15
            }
            includeExcludeFiles(MatchType.EXCLUDE_ALL_MATCHING_CHANGES) {
                filePattern '*.exe'
            }
            excludeChangesetsRegex 'FIXES .*'
            webRepository {
                fisheye {
                    url 'http://localhost:7990'
                    repositoryPath 'a/b/c'
                    repositoryName 'd'
                }
            }
        }

    }
}

scm:
  - !bitbucketServer
    projectKey: project_1
    repoSlug: rep_1
    branch: develop
    serverName: bitbucketServer
    repositoryUrl: ssh://git@localhost:7999/project_1/rep_1.git
    advancedOptions:
      enableRepositoryCachingOnRemoteAgents: true
      useShallowClones: true
      useSubmodules: false
      commandTimeoutInMinutes: 20
      verboseLogs: true
      fetchWholeRepository: false
      enableLfsSupport: true
      quietPeriod:
        waitTimeInSeconds: 10
        maximumRetries: 15
      includeExcludeFiles:
        matchType: !matchType EXCLUDE_ALL_MATCHING_CHANGES
      filePattern: '*.exe'
      excludeChangesetsRegex: 'FIXES .*'
      webRepository:
        type: !fisheyeWeb
          url: http://localhost:7990
            repositoryPath: a/b/c
            repositoryName: d

Git

A definition for plain Git repositories.

scm {
    git(name: 'myGitRepo') {
        url "http://localhost:7990/bitbucket/scm/project_1/java-maven-simple.git"
        branch "master"
        sharedCredentialsPasswordAuth "sharedpw"
        advancedOptions {
            useShallowClones true
            enableRepositoryCachingOnRemoteAgents true
            useSubmodules true
            commandTimeoutInMinutes 20
            verboseLogs true
            fetchWholeRepository true
            quietPeriod {
                waitTimeInSeconds 120
                maximumRetries 3
            }
            includeExcludeFiles(MatchType.EXCLUDE_ALL_MATCHING_CHANGES) {
                filePattern "*.exe"
            }
            excludeChangesetsRegex "FIXES .*"
            webRepository {
                fisheye {
                    url "http://localhost:7990"
                    repositoryPath "a/b/c"
                    repositoryName "d"
                }
            }
        }
    }
}

scm:
  - !git
      name: myGitRepo
      url: http://localhost:7990/bitbucket/scm/project_1/java-maven-simple.git
      branch: master
      authType: !sharedCredentials
        sharedCredentialsType: !sharedCredentialsType USERNAMEPW
        name: sharedpw
      advancedOptions:
        useShallowClones: true
        useSubmodules: true
        commandTimeoutInMinutes: 20
        verboseLogs: true
        fetchWholeRepository: true
        quietPeriod:
          waitTimeInSeconds: 120
          maximumRetries: 3
        includeExcludeFiles:
          matchType: !matchType EXCLUDE_ALL_MATCHING_CHANGES
        filePattern: '*.exe'
        excludeChangesetsRegex: 'FIXES .*'
        webRepository:
          type: !fisheyeWeb
            url: http://localhost:7990
              repositoryPath: a/b/c
              repositoryName: d

GitHub

A definition for GitHub repositories.

scm {
    github(name: 'myGithubRepo') {
        repoSlug 'test/HelloWorld'
        branch 'master'
        passwordAuth {
            userName 'myUser'
        }
        advancedOptions {
            useShallowClones true
            enableRepositoryCachingOnRemoteAgents true
            useSubmodules true
            commandTimeoutInMinutes 20
            verboseLogs true
            fetchWholeRepository true
            quietPeriod {
                waitTimeInSeconds 120
                maximumRetries 3
            }
            includeExcludeFiles(MatchType.EXCLUDE_ALL_MATCHING_CHANGES) {
                filePattern 'exe'
            }
            excludeChangesetsRegex 'FIXES .*'
                webRepository {
                    fisheye {
                        url 'http://localhost:7990'
                        repositoryPath 'a/b/c'
                        repositoryName 'd'
                    }
                }
            }
        }
    }
}

scm:
  - !github
    name: myGithubRepo
    repoSlug: test/HelloWorld
    branch: master
    authType: !password
      userName: myUser
    advancedOptions:
      useShallowClones: true
      useSubmodules: true
      commandTimeoutInMinutes: 20
      verboseLogs: true
      fetchWholeRepository: true
      quietPeriod:
        waitTimeInSeconds: 120
        maximumRetries: 3
      includeExcludeFiles:
        matchType: !matchType EXCLUDE_ALL_MATCHING_CHANGES
      filePattern: '*.exe'
      excludeChangesetsRegex: 'FIXES .*'
      webRepository:
        type: !fisheyeWeb
          url: http://localhost:7990
          repositoryPath: a/b/c
          repositoryName: d

Subversion

A definition for Subversion repositories.

scm {
    subversion(name: 'mySvn') {
        repositoryUrl 'http://svn.red-bean.com/repos/test'
        passwordAuth {
            userName 'admin'
            password 'pw'
        }
        advancedOptions {
            detectChangesInExternals true
            useSvnExport true
            enableCommitIsolation true
            autoDetectRootUrlForBranches false
            branchesRootUrl '/branches'
            autoDetectRootUrlForTags false
            tagRootUrl '/tags'
            quietPeriod {
                waitTimeInSeconds 120
                maximumRetries 3
            }
            includeExcludeFiles(MatchType.EXCLUDE_ALL_MATCHING_CHANGES) {
                filePattern 'exe'
            }
            excludeChangesetsRegex 'FIXES .*'
            webRepository {
                fisheye {
                    url 'http://localhost:7990'
                    repositoryPath 'a/b/c'
                    repositoryName 'd'
                }
            }
        }
    }
}

scm:
  - !subversion
    repositoryUrl: http://svn.red-bean.com/repos/test
    userName: admin
    name: mySvn
    authType: !password
      userName: admin
      password: pw
    advancedOptions:
      detectChangesInExternals: true
      useSvnExport: true
      enableCommitIsolation: true
      autoDetectRootUrlForBranches: false
      branchesRootUrl: /branches
      autoDetectRootUrlForTags: false
      tagRootUrl: /tags
      quietPeriod:
        waitTimeInSeconds: 120
        maximumRetries: 3
      includeExcludeFiles:
        matchType: !matchType EXCLUDE_ALL_MATCHING_CHANGES
        filePattern: exe
      excludeChangesetsRegex: 'FIXES .*'
      webRepository:
        type: !fisheyeWeb
          url: http://localhost:7990
          repositoryPath: a/b/c
          repositoryName: d

Mercurial

A definition for Mercurial repositories.

scm {
    mercurial(name: 'myHg') {
        repositoryUrl 'http://hg.red-bean.com/repos/test'
        branch 'master'
        defaultMercurialCredentials {}
        advancedOptions {
            enableCommitIsolation true
            commandTimeoutInMinutes 180
            verboseLogs true
            disableRepositoryCaching false
            quietPeriod {
                waitTimeInSeconds 120
                maximumRetries 3
            }
            includeExcludeFiles(MatchType.EXCLUDE_ALL_MATCHING_CHANGES) {
                filePattern 'exe'
            }
            excludeChangesetsRegex 'FIXES .*'
            webRepository {
                bitbucket {}
            }
        }
    }
}

scm:
  - !mercurial
    name: myHg
    repositoryUrl: http://hg.red-bean.com/repos/test
    branch: master
    authType: !defaultMercurialAuth
    advancedOptions:
      enableCommitIsolation: true
      commandTimeoutInMinutes: 180
      verboseLogs: true
      disableRepositoryCaching: false
      quietPeriod:
        waitTimeInSeconds: 120
        maximumRetries: 3
      includeExcludeFiles:
        matchType: !matchType EXCLUDE_ALL_MATCHING_CHANGES
        filePattern: exe
      excludeChangesetsRegex: 'FIXES .*'
      webRepository:
       type: !bitbucketWeb

CVS

A definition for CVS repositories.

scm {
    cvs(name: 'myCvsRepo') {
        cvsRoot 'http://localhost:7990/bitbucket/scm/project_1/java-maven-simple.cvs'
        quietPeriodInSeconds 60
        module 'test'
        moduleVersion CvsModuleVersion.HEAD
        passwordAuth {
            password 'pw'
        }
        advancedOptions {
            includeExcludeFiles(MatchType.INCLUDE_ONLY_MATCHING_CHANGES) {
                filePattern 'bat'
            }
            excludeChangesetsRegex 'FIXES .*'
            webRepository {
                fisheye {
                    url 'http://localhost:7990'
                    repositoryPath 'a/b/c'
                    repositoryName 'd'
                }
            }
        }
    }
}

scm:
  - !cvs
    name: myCvsRepo
    cvsRoot: http://localhost:7990/bitbucket/scm/project_1/java-maven-simple.cvs
    quietPeriodInSeconds: 60
    module: test
    moduleVersion: !cvsModuleVersion HEAD
    authType: !password
      password: pw
    advancedOptions:
      includeExcludeFiles:
        matchType: !matchType INCLUDE_ONLY_MATCHING_CHANGES
      filePattern: 'bat'
      excludeChangesetsRegex: 'FIXES .*'
      webRepository
        type: !fisheyeWeb
          url: http://localhost:7990
            repositoryPath: a/b/c
            repositoryName: d

Perforce

A definition for Perforce repositories.

scm {
    perforce(name: 'myPerforceRepo') {
        port '9091'
        client 'perforce'
        depotView '//perforce/workspace'
        environmentVariables 'P4CHARSET=\"utf8\"'
        letBambooManageWorkspace true
        useClientMapping true
        passwordAuth {
            userName 'admin'
            password 'pw'
        }
        advancedOptions {
            quietPeriod {
                waitTimeInSeconds 120
                maximumRetries 3
            }
            includeExcludeFiles(MatchType.EXCLUDE_ALL_MATCHING_CHANGES) {
                filePattern 'exe'
            }
            excludeChangesetsRegex 'FIXES .*'
            webRepository {
                fisheye {
                    url 'http://localhost:7990'
                    repositoryPath 'a/b/c'
                    repositoryName 'd'
                }
            }
        }
    }
}

scm:
  - !perforce
    name: myPerforceRepo
    port: 9091
    client: perforce
    depotView: //perforce/workspace
    environmentVariables: P4CHARSET=utf8
    letBambooManageWorkspace: true
    useClientMapping: true
    passwordAuth: !password
      userName: admin
      password: pw
    advancedOptions:
      quietPeriod:
        waitTimeInSeconds: 120
        maximumRetries: 3
      includeExcludeFiles:
        matchType: !matchType EXCLUDE_ALL_MATCHING_CHANGES
        filePattern: exe
      excludeChangesetsRegex: 'FIXES .*'
      webRepository:
        type: !fisheyeWeb
          url: http://localhost:7990
          repositoryPath: a/b/c
          repositoryName: d

Linked repository

A definition for a linked Bamboo repository. Linked repositories are global to the Bamboo installation.

scm {
    linkedRepository(name: "myGlobalRepo")
}

scm:
  - !linkedRepository
    name: myGlobalRepo

Custom repository

Custom repositories provide a way to use plug-in provided repository types. Here you can see an example for the TFS repository.

scm {
    custom(name: 'MYREPO', pluginKey: 'com.stellarity.bamboo.tfs-repository-plugin:tfs') {
        configure(
            'stellarity.tfs.repository.url': 'https://server/DefaultCollection',
            'stellarity.tfs.repository.path': "\$/proj/SimpleDriver/TheSimpliest",
            'stellarity.tfs.repository.username': 'username',
            'stellarity.tfs.repository.password': encryptionService.encrypt('password'),
            'stellarity.tfs.repository.removeworkspace': true,
            'stellarity.tfs.repository.versionspec': '',
            'selectedWebRepositoryViewer': 'com.stellarity.bamboo.tfs-repository-plugin:tfsViewer',
            'stellarity.tfs.repository.filter.option': 'INCLUDE',
            'stellarity.tfs.repository.filter.pattern': '.*\\.h'
        )
    }
}

scm
  - !customScm
    name: TFS
    pluginKey: com.stellarity.bamboo.tfs-repository-plugin:tfs
    config:
      stellarity.tfs.repository.url: 'https://server/DefaultCollection'
      stellarity.tfs.repository.path: '$/proj/SimpleDriver/TheSimpliest'
      stellarity.tfs.repository.username: username
      stellarity.tfs.temporary.password: !encrypt password
      stellarity.tfs.repository.removeworkspace: true
      stellarity.tfs.repository.versionspec:
      selectedWebRepositoryViewer: 'com.stellarity.bamboo.tfs-repository-plugin:tfsViewer'
      stellarity.tfs.repository.filter.option: INCLUDE
      stellarity.tfs.repository.filter.pattern: '.*\\.h'

Variables

Variables can be declared in build plans, deployment project environment and plan branches.

variables {
    variable 'myKey1', 'myValue1'
    variable 'myKey2', 'myValue2'
}

variables:
  - key: myKey1
    value: myValue1
  - key: myKey2
    value: myValue2

Plan triggers

Plan triggers can be installed on build plans and plan branches.

The following trigger types are supported by the plug-in:

plan(key: 'PLAN1KEY', name: 'my plan 1') {
  triggers {
  }
  branches {
    branch(name: 'develop') {
      triggers {
      }
    }
  }
}

plans:
  - key: MYPLAN
    name: my plan
    triggers:
    # Plan triggers
    branches:
      - name: develop
      triggers:
        # Plan branch triggers

Bitbucket Server trigger

Bitbucket Server triggers the build when changes are committed.

triggers {
    bitbucketServerRepositoryTriggered {
        description 'run when new code'
        repositories 'REPO1', 'REPO2'
    }
}

triggers:
  - !bitbucketServerTrigger
    description: run when new code
    repositories: [REPO1, REPO2]

Scheduled trigger

Run a plan according to a schedule.

triggers {
    scheduled() {
        description 'scheduled'
        cronExpression '0 0 0 ? * *'
        onlyRunIfOtherPlansArePassing {
            planKeys 'PROJKEY-PLANKEY'
        }
    }
}

triggers:
  - !scheduled
    description scheduled
    cronExpression: '0 0 0 ? * *'
    onlyRunIfOtherPlansArePassing:
      planKeys: [PROJKEY-PLANKEY]

Manual trigger

Trigger a build manually in the Bamboo UI.

triggers {
    manual() {
    }
}

triggers:
  - !manual
    description: manually

Polling trigger

Bamboo polls source repository and builds when new changes are found.

triggers {
    polling() {
        description 'mypollsched'
        repositories 'mygit', 'mybitbucket'
        scheduled {
            cronExpression '0 0 0 ? * *'
        }
        onlyRunIfOtherPlansArePassing {
            planKeys 'PROJKEY-PLANKEY'
        }
    }
}

triggers:
  - !polling
    description: mypollsched
    scheduledTrigger:
      cronExpression: '0 0 0 ? * *'
    onlyRunIfOtherPlansArePassing:
      planKeys: [PROJKEY-PLANKEY]

Remote trigger

Repository triggers the build when changes are committed.

triggers {
    remote() {
        description 'my remote trigger'
        repositories 'myrepo'
        ipAddresses '127.0.0.1', '192.168.0.1'
        onlyRunIfOtherPlansArePassing {
            planKeys 'PROJ-PLAN1', 'PROJ-PLAN3', 'PROJ-PLAN5'
        }
    }
}

triggers:
  - !remote
    description: my remote trigger
    repositories: [myrepo]
    ipAddresses: [127.0.0.1, 192.168.0.1]
    onlyRunIfOtherPlansArePassing:
      planKeys: [PROJ-PLAN1, PROJ-PLAN3, PROJ-PLAN5]

Once a day trigger

Single daily build.

triggers {
    onceAday {
        description 'run every day at noon'
        buildTime '12:00'
    }
}

triggers:
  - !onceADay
    description run every day at noon
    buildTime: '12:00'

Notifications

Notifications can be specified on the plan and deployment project level.

The following notification types are supported by the plug-in:

With the custom syntax you can also use plug-in provided notification types not built-in to Bamboo.

plan(key: 'PLAN1KEY', name: 'my plan 1') {
  notifications {
  }
}

plans:
  - key: MYPLAN
    name: my plan
    notifications:
    # Plan notifications

HipChat

Notify users by HipChat.

notifications {
  hipchat(event: NotificationEvent.ALL_BUILDS_COMPLETED, apiToken: 'XXX', room: 'MyRoom') {
    notify true
  }
}

notifications:
  - !hipchat
    apiToken: XXX
    room: MyRoom
    event: !event ALL_BUILDS_COMPLETED
    notify: true

E-Mail

Notify users by e-mail.

notifications {
  email(event: NotificationEvent.FIRST_FAILED_JOB_FOR_PLAN) {
      email 'your@mail.com'
  }
}

notifications:
  - !email
    address: your@mail.com
    event: !event FIRST_FAILED_JOB_FOR_PLAN

Stash Legacy

This notification type is obsolete and should no longer be used. Bamboo notifies Bitbucket Server about every build result automatically.

notifications {
  stashLegacy(event: NotificationEvent.CHANGE_OF_JOB_STATUS) {
  }
}

notifications:
  - !stashLegacy
    event: !event CHANGE_OF_JOB_STATUS

Group notification

Notify Bamboo user groups.

notifications {
  group(event: NotificationEvent.CHANGE_OF_JOB_STATUS) {
      group 'mygroup'
  }
}

notifications:
  - !group
    event: !event CHANGE_OF_JOB_STATUS
    group: mygroup

User notification

Notify individual Bamboo users.

notifications {
  user(event: NotificationEvent.FAILED_JOBS_AND_FIRST_SUCCESSFUL) {
      user 'bob'
  }
}

notifications:
  - !user
    event: !event FAILED_JOBS_AND_FIRST_SUCCESSFUL
    user: bob

IM address notification

Notify users by their instant messanger address.

notifications {
  imAddress(event: NotificationEvent.FAILED_JOBS_AND_FIRST_SUCCESSFUL) {
      instantMessagingAddress 'bill@chat.com'
  }
}

notifications:
  - !imAddress
    event: !event FAILED_JOBS_AND_FIRST_SUCCESSFUL
    instantMessagingAddress: bill@chat.com

Responsible users notification

Notify responsible users.

notifications {
  responsibleUsers(event: NotificationEvent.ALL_JOBS_COMPLETED) {
  }
}

notifications:
  - !responsibleUsers
     event: !event ALL_JOBS_COMPLETED

Committers notification

Notify users who have committed to the build.

notifications {
  committers(event: NotificationEvent.CHANGE_OF_BUILD_STATUS) {
  }
}

notifications:
  - !committers
    event: !event CHANGE_OF_BUILD_STATUS

Watchers notification

Notify users who have marked this build as their favourite.

notifications {
  watchers(event: NotificationEvent.FIRST_FAILED_JOB_FOR_PLAN) {
  }
}

notifications:
  - !watchers
    event: !event FIRST_FAILED_JOB_FOR_PLAN

Custom notification

A custom (i.e., not built-in) notification.

notifications {
  custom(event: NotificationEvent.AFTER_X_BUILD_FAILURES,
    pluginKey: 'ch.mibex.bamboo.smsnotification:smsnotification.recipient') {
    numberOfFailures 1
    configure(
            twilioAccountSid: 'twilioAccountSid',
            twilioAuthToken: 'twilioAuthToken',
            smsFromNumber: 'smsFromNumber',
            smsToNumber: 'smsToNumber'
    )
  }
}

notifications:
  - !customNotification
    event: !event FAILED_BUILDS_AND_FIRST_SUCCESSFUL
    notificationRecipientType: ch.mibex.bamboo.smsnotification:smsnotification.recipient
    numberOfFailures: 1
    config:
      twilioAccountSid: [!env twilioAccountSid]
      twilioAuthToken: [!env twilioAuthToken]
      smsFromNumber: [!env smsFromNumber]
      smsToNumber: [!env smsToNumber]

Permissions

Can be used to configure permissions on plan, deployment project and environment level.

Permissions apply to users, groups and special user groups like logged-in and anonymous users. The permission types correspond to the ones shown in the Bamboo UI.

 permissions {
    user(name: 'diego') {
        permissionTypes PermissionType.EDIT, PermissionType.CLONE, PermissionType.BUILD
    }

    group(name: 'devops') {
        permissionTypes PermissionType.VIEW, PermissionType.BUILD
    }

    other(type: OtherUserType.ANONYMOUS_USERS) {
        permissionTypes PermissionType.VIEW
    }
}

permissions:
  user:
    diego: 
      - !permission EDIT
      - !permission CLONE
      - !permission BUILD
  group:
    devops: 
      - !permission VIEW
      - !permission BUILD
  other:
    !userType ANONYMOUS_USERS: 
      - !permission VIEW

Deployment projects

A deployment project consists of a description, the name of the associated plan branch (if not the default one), a number of deployment environments and release versioning information.

Note that the ID for both the deployment projects and the environments is optional and will be auto-generated if not specified.

plan(key: 'SIMPLEPLAN', name: 'my simple plan') {
    deploymentProject(name: 'DP1', id: 1) {
        description 'my deployment project'
        useCustomPlanBranch 'PLAN_BRANCH_NAME'

        environment(name: 'staging', id: 1) {
            description 'Staging env'
        }
        environment(name: 'prod', id: 2) {
            description 'Production env'
        }
        releaseVersioning(nextReleaseVersion: '1.0-${bamboo.buildNumber}') {
            autoIncrement()
            applicableToBranches()
            variables 'var1', 'var2'
        }
        permissions {
        }
    }
}

plans:
  - key: SIMPLEPLAN
    name: my simple plan
    deploymentProjects:
      - id: 1
        name: DP1
        description: my deployment project
        useCustomPlanBranch: PLAN_BRANCH_NAME
        environments:
          - name: staging
            id: 1
            description: Staging env
          - name: prod
            id: 2
            description: Production env
        releaseVersioning:
           nextReleaseVersion: 1.0-${bamboo.buildNumber}
           autoIncrement: true
           applicableToBranches: true
           variables:
             - var1
             - var2
        permissions:

Environments

A deployment project environment consists of tasks, build variables, notifications, permissions and triggers.

Note that the ID for both the deployment projects and the environments is optional and will be auto-generated if not specified.

deploymentProject(name: 'DP1', id: 1) {
    environment(name: 'staging', id: 1) {
        description 'Staging env'
        tasks {
        }
        triggers {
        }
        variables {
        }
        notifications {
        }
        permissions {
        }
        agentsAssignment {
        }
    }
}

deploymentProjects:
  - id: 1
    name: DP1
    environments:
      - name: staging
        id: 1
        description: Staging env
        tasks:
        variables:
        notifications:
        permissions:
        triggers:
        agentsAssignment:

Agent assignments

An environment can only be deployed by agents whose capabilities meet these requirements.

environment(name: 'staging', id: 1) {
    agentsAssignment {
        requirements {
            requirement(capabilityKey: 'system.builder.gradle.Gradle 2.2',
                        matchType: equalsTo("2.2")) {
            }
        }
        dedicatedAgents 'local agent', 'remote agent'
    }
}

environments:
  - name: staging
    agentsAssignment:
      requirements:
        - capabilityKey: system.builder.gradle.Gradle 2.2
          matchType: !equals
            matchValue: 2.2
      dedicatedAgentNames:
        - local agent
        - remote agent

Environment triggers

The following trigger types are supported for deployment project environments:

environment(name: 'staging', id: 1) {
    description 'Staging env'
    triggers {
    }
}

environments:
  - name: staging
    id: 1
    description: Staging env
    triggers:

Scheduled trigger

Run according to schedule.

environment(name: 'staging', id: 1) {
    triggers {
        scheduledCron(cronExpression: '0 0 0 6 * *') {
            customPlanBranchName: 'MYPLANBRANCH'
        }
    }
}

environments:
  - name: staging
    id: 1
    triggers:
      - !scheduledDeployment
        cronExpression: 0 0 0 6 * *
        customPlanBranchName: MYPLANBRANCH

After successful build plan

Deployment is started after a plan is successfully built.

environment(name: 'staging', id: 1) {
    triggers {
        afterSuccessfulBuildPlan() {
            customPlanBranchName 'DEV'
        }
    }
}

environments:
  - name: staging
    id: 1
    triggers:
      - !afterSuccessfulBuildDeployment
        customPlanBranchName: DEV

After successful stage trigger

Deployment is started after a stage is successfully built.

environment(name: 'staging', id: 1) {
    triggers {
        afterSuccessfulStage() {
            planStageToTriggerThisDeployment 'STAGE1'
            customPlanBranchName 'TEST'
        }
    }
}

environments:
  - name: staging
    id: 1
    triggers:
      - !afterSuccessfulStageDeployment
        planStageToTriggerThisDeployment: STAGE1
        customPlanBranchName: TEST

After successful deployment trigger

Deployment is started after a deployment on another environment is completed successfully.

environment(name: 'staging', id: 1) {
    triggers {
        afterSuccessDeployment(triggeringEnvironment: 'PROD') {
        }
    }
}

environments:
  - name: staging
    id: 1
    triggers:
        - !afterSuccessfulDeployment
          triggeringEnvironment: PROD