It operates by your build and deployment processes making a request to Plandek’s API. We recommend that you do this at the end of your production deployment pipeline. This needs data about the HEAD commit sha, repo, and deployment status.

If you have a two-stage build process, i.e. a pipeline that builds an artifact and another pipeline that does the deployment which does not know the commit, we have the ability to map a tag to a commit. This requires that you use the save_mapping endpoint detailed below at the end of your artifact build pipeline and send only the build in your save request.

OPTIONAL: We recommend that you send us historical build information too - we are able to provide advice and code snippets around shipping this data to Plandek. Whilst not required to start using the Pipeline API, having historical data helps understand trends.

Please note: You will need an access token to successfully call the API. To obtain your unique token, please contact us at support@plandek.com

Host:

https://pipelines.plandek.com

API Methods:

Save data about a deployment into the db

Save data about a build - commit mapping into the db

Save commencement

1. Save data about a deployment into the db:

/deployments/v1/save?client_key=&access_token=&commit=&pipeline=&build=&status=

optional params: deployed_at (ISO date string including timezone. Defaults to current time if omitted.)

Commit sha should be the HEAD commit of the release being deployed, it is optional if you have previously called save_mapping.

Build should be the build identifier in your pipeline management tool.

Status should be one of: success, failure, rollback

Example

Send data to the pipelines API:

curl "https://pipelines.plandek.com/deployments/v1/save?client_key=plandek&access_token=...&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 data about a build - commit mapping into the db:

/deployments/v1/save_mapping?client_key=&access_token=&commit=&build=&pipeline=

Example

By saving a mapping using /save_mapping, future requests to /save can omit one of build or commit, for example:

curl "https://jenkins-connector-prd.plandek.com/deployments/v1/save_mappingclient_key=plandek&access_token=...&build=mybuild&commit=a1b2c3d4&pipeline=chapp"

Response:

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

"status":"OK"}

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.

Mappings are unique, and further requests to /save_mapping with matching build or commit values will overwrite old data.

3. Save commencement

There is a new endpoint /save_commencement to save the commencement time of a deployment, which expects the following parameters:

client_key

access_token

pipeline

To at least one of build or commit or branch_name

Optional:

commenced_at ISO Date string. If this is omitted, then the current time is used.

For example:

curl "https://jenkins-connector-prd.plandek.com/deployments/v1/save_commencement?client_key=...&access_token=...&pipeline=mypipeline&build=build-1&commenced_at=2020-09-17T11%3A00%3A00.500000Z"

response:

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

"commit": "3f6cf8c685d8fbf87282f0509871ea001403fee0",

"branch_name":null,

"client_key":"...",

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

"pipeline":"mypipeline"},

"status":"OK"}

On completion of the deployment, call the existing /save endpoint as usual:

curl "https://jenkins-connector-prd.plandek.com/deployments/v1/save?client_key=ctest&access_token=SF7IqCwVRgbNEnak1SacxMWIDRe0JyXoOGNlNwIYO0A&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.

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.

Did this answer your question?