Plandek's pipeline integration makes it simple to integrate any CI/CD tool in order to track and visualise your production deployments in a variety of metrics, including the very popular DORA metrics: Lead time for Change, Deployment Frequency, and Change Failure Rate.

Example of the DORA deployment metrics

Additionally, Plandek uses these deployment requests to identify the Pull Requests (PRs) and tickets contained in the release, so you can see the full lifecycle of your PRs and Tickets - not just up until the ticket was closed in Jira/Azure or the PR merged in git.

Example of Code Cycle Time including Time to Deploy

Below we will cover:

  1. Steps required to setup and start sending deployments to Plandek

  2. The 3 methods our API supports

  3. How you can test and validate the data

  4. Common errors

  5. Sending historical data

Setting up the integration with the Pipeline API

The first step is to request your API token from us. You can email us at support@plandek.com or send a message through the chat in Plandek (bottom left corner of the product).

The URL for the API is: https://pipelines.plandek.com/deployments/v1

Please note: this API currently only supports production deployments. All requests made will be assumed to be production level deployments in terms of how the deployment time is associated to PRs and tickets, and how that time is subsequently displayed in metrics like Lead Time, Cycle Time and Code Cycle Time.


Authentication

Plandek will provide you with an access token for authentication. Please include this as an Authorization: Bearer header in all requests. For example if your token is abcde:

curl -H "Authorization: Bearer abcde" https://pipelines.plandek.com...


The 3 methods the API supports

The API provides 3 methods to support a number of use cases for production deployments (non-prod deployments should not be sent to this API):

/save

The standard method to use when you have all the required parameters available at the end of the deployment process (when we recommend you call the Pipeline API)

/save_mapping

If you don't have all the parameters when you deploy (e.g. you build in one tool and deploy in another), you will use the /save_mapping method to store the parameters in advance before eventually calling /save when you deploy

/save_commencement

If you wish to calculate the time it takes you to deploy (e.g. you have a combination of automated and manual steps), you can track the overall deployment time by using the /save_commencement method to start the clock (and stop the clock by calling /save method). There is also a param in the /save method to do this (see below)

Supported parameters

Parameter

Required

Description

client_key

Yes, for all requests

Unique identifier for your instance

pipeline

Yes, for all requests

Typically corresponds to the name of your pipeline, workflow, repo, or service under which builds are compiled.

build

Yes, for all requests

Build identifier in your build tool. Typically the version being deployed (e.g. Svc B 10.2.1).

commit

Must be provided in either the /save request or /save_mapping

The full commit hash of the release being deployed

context

optional

This is an optional parameter that can be used in the UI to filter or differentiate deployments on a broader level (e.g. if you use different CI/CD tools and want to compare deployment data between them)

status

Yes, for /save

The status of the deployment. Must be "success", "failure", "rollback" or "aborted"

deployed_at

Optional

Timestamp when deployment finished. ISO date string including timezone. If this is not provided in the request, the current time will be used.

branch_name

Optional

An optional parameter for the /save_commencement method when the build parameter is not known.

commenced_at

Optional

Timestamp when deployment process started. ISO date string including timezone. If this is not provided in the /save_commencement request, the current time will be used. If it is not included in the /save request, the commencement time will not be recorded (i.e. no deployment time will be calculated)

How commits are used by Plandek

For the first deployment you send to the API, Plandek will associate the deployment with the commit provided. Each subsequent deployment will be associated with the provided commit and its ancestors back to the previously deployed commit.

All tickets and PRs linked to these commits will also be associated with the deployment. Therefore, you will not see deployment data related to PRs and tickets until you have sent at least two deployments to the API for a given pipeline.

How to use each method

1. /save method - sending your deployment data to Plandek

We recommend that you call the /save method at the end of your deployment process when you know the outcome of the release (i.e. the "status")

Request:

https://pipelines.plandek.com/deployments/v1/save?client_key=&commit=&pipeline=&build=&status=

Required params: client_key, pipeline, build, status

Optional params: context, deployed_at, commit, commenced_at

Important: the "commit" param is only optional if you have previously sent the pipeline+build+commit to /save_mapping. If you haven't, the request will fail. So please ensure that it is provided in one of the two requests.

Sample request

curl -H "Authorization: Bearer <access_token>" "https://pipelines.plandek.com/deployments/v1/save?client_key=plandek&status=success&pipeline=chapp&build=historical-chapp-1&commit=3f6cf8c685d8fbf87282f0509871ea001403fee0&deployed_at=2017-01-26T11%3A37%3A06.690000Z"

Response:

{"deployment":{"client_key":"plandek",

"commit":"3f6cf8c685d8fbf87282f0509871ea001403fee0",

"deployed_at":"Thu, 26 Jan 2017 11:37:06 GMT",

"pipeline":"chapp",

"status":"success"},

"status":"OK"}

An HTTP Response code of 401 is returned if the access_token is incorrect

2. /save_mapping - when you don't have all parameters handy at deployment

Since not all teams will have the full set of required parameters (i.e. pipeline, build and commit) at the point of final production deployment, we offer a method to store the required parameters in advance.

Note the /save_mapping method is optional. You do not need to store a mapping of these parameters if you have all the parameters when you release (i.e. you would only need to call the /save method above)

Please note that the parameters are case sensitive, so ensure that the values sent will be the same case as they will be when /save is called

Request

https://pipelines.plandek.com/deployments/v1/save_mapping?client_key=&commit=&build=&pipeline=

Required params: client_key, pipeline, build, commit

Important: mappings are unique; further requests to /save_mapping with matching build or commit values will overwrite old data.

Sample request

curl -H "Authorization: Bearer <access_token>" "https://pipelines.plandek.com/deployments/v1/save_mapping?client_key=plandek&build=mybuild&commit=a1b2c3d4&pipeline=chapp"

Response:

{"mapping": {"build": "mybuild", "commit":"a1b2c3d4"},

"status":"OK"}

When you are ready to deploy to production (using the sample request above):

A subsequent request to /save with no commit value and build=mybuild would assume a commit value of "a1b2c3d4". Similarly a subsequent request to /save with no build value and commit=a1b2c3d4 would assume a build value of "mybuild".

3. /save_commencement - when you would like to calculate the time it takes to run the deployment process

Some teams have a set of automated and manual steps they undertake as part of the deployment process and would like to measure how long this process takes over time (in case improvements are made and you want to demonstrate them). In that case, you can essentially "start the clock" with Plandek by calling /save_commencement at the start of the process, and "stop the clock" when you make the final /save call.

Request

https://pipelines.plandek.com/deployments/v1/save_commencement?client_key=&commit=&pipeline=&build=

Required params: client_key, pipeline

And at least one of the following is also required: build, branch_name, commit

Optional params: commenced_at (if this is not provided, the current time will be used)

Sample request

curl -H "Authorization: Bearer <access_token>" "https://pipelines.plandek.com/deployments/v1/save_commencement?client_key=plandek&pipeline=mypipeline&build=build-1&commenced_at=2020-09-17T11%3A00%3A00.500000Z"

Response:

{"commencement":{"build":null,

"commit": "3f6cf8c685d8fbf87282f0509871ea001403fee0",

"branch_name":null,

"client_key":"plandek",

"commenced_at":"Thu, 17 Sep 2020 11:00:00 GMT",

"pipeline":"mypipeline"},

"status":"OK"}

Upon completion of the deployment...

Call the existing /save endpoint as usual:

curl -H "Authorization: Bearer <access_token>" "https://pipeline.plandek.com/deployments/v1/save?client_key=plandek&status=success&pipeline=mypipeline&build=build-1&commit=3f6cf8c685d8fbf87282f0509871ea001403fee0&deployed_at=2020-09-17T11%3A01%3A00.120000Z"

The response includes the commenced_at time from the earlier request:

{"deployment":{"client_key":"...",

"commenced_at":"Thu, 17 Sep 2020 11:00:00 GMT",

"Commit":"3f6cf8c685d8fbf87282f0509871ea001403fee0",

"branch_name":null,

"deployed_at":"Thu, 17 Sep 2020 11:01:00 GMT",

"pipeline":"mypipeline",

"status":"success"},

"status":"OK"}

The API uses the pipeline and build/commit/branch_name fields to link the deployment with the commencement. The pipeline must match and at least one of build/commit/branch_name must match also. Where there are multiple matching commencements (for example a commencement was saved with a build and another with a commit) then the most recently updated commencement is used.

Note: The /save method can also accept a commenced_at parameter. If this is provided, then there is no need to make the /save_commencement request.

3. How you can validate your data in Plandek

Assuming you received the expected "success" responses above, Plandek will gather your deployments incrementally and process them, typically every 30-60 minutes. That means that your data will appear in the metrics no more than 30-60 minutes later. We can reduce this to 10 minutes during testing; just contact our Customer Success team.

Once the data is gathered and processed, you will see the pipelines appear under "Deployment Pipelines" in your workspace settings (see below). Simply select the pipelines that you would like to include in the respective workspace data.

Note: the available pipelines are cached, so there can be a slight delay until they refresh. If you have successfully sent the request and the pipelines are not showing up, simply contact us and we'll refresh the list for you.

The simplest way to verify the data is to add the Number of Deployments metric to a dashboard. From there, you can click on any of the data points in the chart to see a drill down of the deployments you sent.

Example of the Number of Deployments metric

Clicking on a data point in the chart shows the drill down of deployments

In order to validate the deployment date for PRs and tickets, please read how commits are used by Plandek.

4. Common Errors

HTTP 401 response code: the client_key and access_token are not valid. Please check both and confirm spelling.

"build mapping not found": If you call /save and receive this error, Plandek has not received all required parameters and therefore is looking in the /save_mapping table for the corresponding data. If we cannot find the data, the API will respond with this error.

HTTP 400 response code with responses:

The following responses may be provided in 400 errors, confirming the nature of the error and related parameter:

  • Date format is incorrect: Invalid date format for <parameter>

  • Timezone is not included in date format: Missing timezone from <parameter>

  • Required parameter is missing: <parameter> is required

  • Invalid status provided: Invalid status <status>. Must be one of success/failure/rollback/aborted

For more information on how Plandek uses your commits, please read here

5. Sending historical deployment data

We highly recommend that you send us historical deployment information. Whilst it's not required to start using the Pipeline API, having historical data helps you understand and communicate trends.

Our API supports historical data in the same way as it does for current/future deployments. Using the /save method above, you can generate a script that sends your historical deployments to Plandek. You will need to update the "deployed_at" parameter for each request to reflect the date/time when the deployment occurred.

Did this answer your question?