REST API deployment triggers for Bamboo

You can trigger deployment via REST in two different ways, depending on the information that is available.

Prerequisites

Install jq to parse JSON in the command line. Alternatively, you can use Ruby, Python, or AWK.

Option 1: Triggering deployments when I only know the deployment project name, the environment name, and the version name

To deploy in this scenario, you'll need

• the deployment project ID
• the ID of the environment to which you want to deploy
• the release version ID

To get to the data required for triggering a deployment you'll have to:

1. Find the project ID in the list of deployment projects.
2. Check the list of environments available for the project ID.
3. Check which releases are available for the project ID.

After that you can trigger the deployment and check its status.

Finding the project ID

To get the list of deployment projects by name and ID, run the following:

1
2
curl 'http://localhost:9087/bamboo/rest/api/latest/deploy/project/all' -u admin:admin -H "Accept: application/json" | jq '.[] | {name: .name,id: .id}'

Let's say we got the following output:

1
2
{
  "name": "Commons",
  "id": 7405569
}
{
  "name": "Failing",
  "id": 8028161
}
{
  "name": "Test project 2",
  "id": 27951105
}

I know that I want to deploy the Commons project, so I note down it's ID: 7405569.

Checking the list of environments available for a project ID

To get the list of environments available for the Commons project by name and ID, run the following:

1
2
curl 'http://localhost:9087/bamboo/rest/api/latest/deploy/project/7405569' -u admin:admin -H "Accept: application/json" | jq '.environments[] | {id: .id, name: .name}'

Let's say that we got the following output:

1
2
{
  "id": 7536641,
  "name": "Staging"
}
{
  "id": 7536642,
  "name": "QA"
}
{
  "id": 7536643,
  "name": "Production"
}

I know that I want to deploy to the Staging environment, so I note down it's ID: 7536641.

Checking the list of releases available for the project ID

To get the list of releases by name and ID, run the following:

1
2
curl 'http://localhost:9087/bamboo/rest/api/latest/deploy/project/7405569/versions' -u admin:admin -H "Accept: application/json" | jq '.versions[] | {id: .id, name: .name}'

Let's say that we got the following output:

1
2
{
  "id": 7602178,
  "name": "release-2"
}
{
  "id": 7602177,
  "name": "release-1"
} 

I know that I want to deploy release-2, so I note down it's ID: 7602178.

Triggering a deployment

Now let's trigger a deployment of release-2 to the Staging environment:

1
2
curl -X POST 'http://localhost:9087/bamboo/rest/api/latest/queue/deployment/?environmentId=7536641&versionId=7602178' -u admin:admin -H "Accept: application/json" | jq '.'

Here's an example of a response:

1
2
{
  "deploymentResultId": 28639233,
  "link": {
    "href": "http://localhost:9087/bamboo/rest/api/latest/deploy/result/28639234",
    "rel": "self"
  }
}

Checking the status of a deployment

You can get the deployment status result to check if the deployment succeeded or failed:

1
2
curl 'http://localhost:9087/bamboo/rest/api/latest/deploy/result/28639234' -u admin:admin -H "Accept: application/json" | jq '.'

Here's an example of a response:

1
2
{
  "deploymentVersion": {
    "id": 7602178,
    "name": "release-2",
    "creationDate": 1386782176519,
    "creatorUserName": "admin",
    "items": [],
    "operations": {
      "canView": true,
      "canEdit": true,
      "canDelete": true,
      "allowedToExecute": false,
      "canExecute": false,
      "allowedToCreateVersion": true,
      "allowedToSetVersionStatus": true
    },
    "creatorDisplayName": "Administrator",
    "creatorGravatarUrl": "https://secure.gravatar.com/avatar/70572fd824e6a3a72ce0cd2877ba8af6.jpg?r=g&s=24&d=mm",
    "planBranchName": "com.atlassian.connector.commons",
    "ageZeroPoint": 1458223960182
  },
  "deploymentVersionName": "release-2",
  "id": 28639234,
  "deploymentState": "UNKNOWN",
  "lifeCycleState": "QUEUED",
  "startedDate": 1458223960181,
  "queuedDate": 1458223960185,
  "reasonSummary": "Manual run by <a href=\"http://beloe:9087/bamboo/browse/user/admin\">Administrator</a>",
  "key": {
    "key": "7405569-7536641-28639234",
    "entityKey": {
      "key": "7405569-7536641"
    },
    "resultNumber": 28639234
  },
  "operations": {
    "canView": true,
    "canEdit": true,
    "canDelete": false,
    "allowedToExecute": true,
    "canExecute": false,
    "cantExecuteReason": "Cannot deploy at this time. Environment is currently being deployed to.",
    "allowedToCreateVersion": false,
    "allowedToSetVersionStatus": false
  }
}

In the example above we can see that the status (lifeCycleState) is QUEUED. You can also check that in the GUI:

Getting the deployment queue 

To check the deployment queue, run:

1
2
curl 'http://localhost:9087/bamboo/rest/api/latest/queue/deployment' -u admin:admin -H "Accept: application/json"

Here's an example of a response:

1
2
{
  "expand": "queuedDeployments",
  "link": {
    "href": "http://localhost:9087/bamboo/rest/api/latest/queue/deployment",
    "rel": "self"
  },
  "queuedDeployments": {
    "size": 1,
    "start-index": 0,
    "max-result": 1
  }
}

The queue has only one item, but we can't see any details. The /queue/deployment endpoint returns deployments only.

If you want to see your builds, use the /queue endpoint that returns only builds in the queue.

Viewing a queued deployment's details

Look at expand field in the example above. Its value contains possible values of the expand query parameter that expands collection fields. To view a queued deployment's details, run:

1
2
curl 'http://localhost:9087/bamboo/rest/api/latest/queue/deployment?expand=queuedDeployments' -u admin:admin -H "Accept: application/json"

Here's an example of a response:

1
2
{
  "expand": "queuedDeployments",
  "link": {
    "href": "http://localhost:9087/bamboo/rest/api/latest/queue/deployment",
    "rel": "self"
  },
  "queuedDeployments": {
    "size": 1,
    "expand": "queuedDeployments",
    "queuedDeployments": [
      {
        "deploymentResultId": 28639234,
        "link": {
          "href": "http://localhost:9087/bamboo/rest/api/latest/deploy/result/28639234",
          "rel": "self"
        }
      }
    ],
    "start-index": 0,
    "max-result": 1
  }
}

Deleting a deployment from a queue

To remove a deployment from a queue, run:

1
2
curl -X DELETE 'http://localhost:9087/bamboo/rest/api/latest/queue/deployment/28639234' -u admin:admin -H "Accept: application/json"

If the deployment is successfuly deleted, you'll see the 204 HTTP code result.

Option 2: Triggering deployments when I only know the deployment project ID, the environment ID, and the build result that I want to deploy

To deploy in this scenario, you'll need

• the deployment project ID (Finding the project ID)
• the ID of the environment to which you want to deploy (Checking the list of environments available for a project ID)
• the key of the build result that you want to deploy

Creating a deployment release

First, create a deployment release called release-3 from the build result with the ACC-TST-9 key:

Note: The *ACC-TST-9 *result is the 9th build result of the plan called ACC-TST.

1
2
curl -X POST 'http://localhost:9087/bamboo/rest/api/latest/deploy/project/7405569/version' -u admin:admin -H "Accept: application/json" -H "Content-Type: application/json" -d '{"planResultKey" : "ACC-TST-9", "name" : "release-3"}' | jq '.'

Here's an example of a response:

1
2
{
    "id": 28803073,
    "name": "release-3",
    "creationDate": 1458227142027,
    "creatorUserName": "admin",
    "items": [
        {
            "id": 28868609,
            "name": "Text",
            "planResultKey": {
                "key": "ACC-TST-9",
                "entityKey": {
                    "key": "ACC-TST"
                },
                "resultNumber": 9
            },
            "type": "BAM_ARTIFACT",
            "label": "Text",
            "location": "",
            "copyPattern": "text.txt",
            "size": 12,
            "artifact": {
                "id": 28672003,
                "label": "Text",
                "size": 12,
                "isSharedArtifact": true,
                "isGloballyStored": false,
                "linkType": "com.atlassian.bamboo.plugin.artifact.handler.local:ServerLocalArtifactHandler",
                "planResultKey": {
                    "key": "ACC-TST-9",
                    "entityKey": {
                        "key": "ACC-TST"
                    },
                    "resultNumber": 9
                },
                "archiverType": "NONE"
            }
        }
    ],
    "operations": {
        "canView": true,
        "canEdit": true,
        "canDelete": true,
        "allowedToExecute": false,
        "canExecute": false,
        "allowedToCreateVersion": true,
        "allowedToSetVersionStatus": true
    },
    "creatorDisplayName": "Administrator",
    "creatorGravatarUrl": "https://secure.gravatar.com/avatar/70572fd824e6a3a72ce0cd2877ba8af6.jpg?r=g&s=24&d=mm",
    "planBranchName": "master",
    "ageZeroPoint": 1458227142027
}

1
2
${bamboo.variable.name}

1
2
{"planResultKey" : "ACC-TST-9", "name" : "release-${bamboo.variable.name}"}'

Deploying a release

Once you created the release, you can deploy it. Let's say that you're deploying it to the required environment with the ID 7536641:

1
2
curl -X POST 'http://localhost:9087/bamboo/rest/api/latest/queue/deployment/?environmentId=7536641&versionId=28803073' -u admin:admin -H "Accept: application/json" | jq '.'