Release & Build Deployment
- 21 Jan 2023
- 11 Minutes to read
- Print
- DarkLight
- PDF
Release & Build Deployment
- Updated on 21 Jan 2023
- 11 Minutes to read
- Print
- DarkLight
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
The Release & Build Deployment API offers a simple mechanism for creating releases, creating builds, and deploying builds.
API Usage
All of these endpoints require that an API Key with Release & Build Deployment access is passed into each request. The examples use a query string for simplicity, but you could also use a header, form value, or JSON property. See Using API Keys for more information.
Data Specification
This endpoint receives data entirely as key/value parameters and sends data using the following JSON objects:
Release
| Property | Format |
|---|---|
id | An integer representing the system-unique identifier of the release. |
releaseNumber | A string representing the application-unique identifier of the release. |
releaseName | A string representing the non-unique name or alias for the release. |
sequence | An integer representing the sequence relative to other releases in the application. |
template | A string of the template name used for this release, or null if no template is used. |
status | A string consisting of active, deployed, or canceled. |
createdBy | A string representing the user who created the release, or SYSTEM if created non-interactively. |
createdOn | A string representing the UTC date when the release was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
canceledBy | A string representing the user who canceled the release, or SYSTEM if created non-interactively. |
canceledOn | A string representing the UTC date when the release was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
targetDate | A string representing the UTC date of the target release date in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
applicationId | An integer representing the system-unique identifier of the application for the release. |
applicationName | A string representing the system-unique name of the application for the release. |
pipelineName | A string representing the name of the pipeline used by the release. |
furthestBuildId | An integer representing the system-unique identifier of the active or deployed build that has made it furthest in the pipeline for the release. |
furthestBuildNumber | A string representing the application-unique number of the active or deployed build that has made it furthest in the pipeline for the release. |
latestBuildId | An integer representing the system-unique identifier of the active or deployed build that was most recently created. |
latestBuildNumber | A string representing the application-unique number of the active or deployed build that was most recently created. |
Build
| Property | Format |
|---|---|
id | An integer representing the system-unique identifier of the build. |
buildNumber | A string representing the release-unique identifier of the build. |
status | A string consisting of active, deployed, or rejected. |
createdBy | A string representing the user who created the build, or SYSTEM if created non-interactively. |
createdOn | A string representing the UTC date when the build was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
rejectedBy | A string representing the user who rejected the build, or SYSTEM if rejected non-interactively. |
rejectedOn | A string representing the UTC date when the build was rejected, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
pipelineName | A string representing the name of the pipeline used by the build. |
furthestStage | A string representing the name the furthest stage the build has advanced to in the pipeline. |
applicationId | An integer representing the system-unique identifier of the application for the build. |
applicationName | A string representing the system-unique name of the application for the build. |
releaseId | An integer representing the system-unique identifier of the release for the build. |
releaseNumber | A string representing the application-unique number of the release for the build. |
releaseName | A string representing the name of the release for the build. |
Deployment
| Property | Format |
|---|---|
id | An integer representing the system-unique identifier of the deployment. |
plan | A string representing the name of the plan used for deployment. |
status | A string consisting of pending, executing, succeeded, warned, or failed. |
started | A string representing the UTC date when the deployment actually started, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the execution hasn't started. |
ended | A string representing the UTC date when the deployment completed, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the execution hasn't completed. |
createdBy | A string representing the user who initiated the deployment, or SYSTEM if initiated non-interactively. |
createdOn | A string representing the UTC date when the deployment was initiated, in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
canceledBy | A string representing the user who canceled the deployment (SYSTEM if canceled non-interactively), or null if the deployment was not canceled. |
canceledOn | A string representing the UTC date when the deployment was canceled, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the deployment was not canceled. |
pipelineName | A string representing the name of the pipeline used by the deployment. |
pipelineStageName | A string representing the name the stage in the pipeline used by the deployment. |
environmentId | An integer representing the system-unique identifier of the environment used by the deployment, or null if no environment is in context. |
environmentName | A string representing the name of the environment used by the deployment, or null if no environment is in context. |
applicationId | An integer representing the system-unique identifier of the application for the deployment. |
applicationName | A string representing the system-unique name of the application for the deployment. |
releaseId | An integer representing the system-unique identifier of the release for the deployment. |
releaseNumber | A string representing the application-unique number of the release for the deployment. |
releaseName | A string representing the name of the release for the deployment. |
buildId | An integer representing the system-unique identifier of the build for the deployment. |
buildNumber | A string representing the release-unique number of the build for the deployment. |
In BuildMaster 6.1 and earlier, these data objects contained a pipelineId which was an integer identifier for the pipeline used by the release. However, since BuildMaster 6.2, pipelines are stored in raft repositories (which can be a zip file or a git repository) and therefore no longer have a native identifier.
Endpoint Specifications
This endpoint receives data entirely as key/value parameters, which may be specified in both the querystring and body (application/x-www-form-urlencoded); duplicate keys will result in an failed request (400 status).
Get Releases
GET or POST /api/releases
Returns a status of 200 and a body with an array of release objects based on the specified optional filter parameters:
| Filter | Parameter Specification |
|---|---|
| Application | Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release | Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value. |
| Pipeline | A key named pipelineName with any value. |
| Status | A key named status with a value of active, canceled, or deployed. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Create Release
POST or PUT /api/releases/create
Returns a status of 200 and a body with a release object that was created with the following input parameters:
| Input | Parameter Specification |
|---|---|
| Application | Required. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release Number | Required. A key named releaseNumber with any value. |
| Pipeline | Required. A key named pipelineName with any value. |
| Release Name | Optional. A key named releaseName with any value. |
| Variables | Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Create Release from Template
POST or PUT /api/releases/create-from-template
Returns a status of 200 and a body with a release object that was created with the following input parameters:
| Input | Parameter Specification |
|---|---|
| Application | Required. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release Number | Required. A key named releaseNumber with any value. |
| Template | Required. A key named template with any value. |
| Release Name | Optional. A key named releaseName with any value. |
| Pipeline Name | Optional. Available in BuildMaster 7.0.22+, a key named pipelineName with the name of a valid pipeline. When set, this overrides the value in the Template. |
| Variables | Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Cancel Release
POST or PUT /api/releases/cancel
Returns a status of 200 if the release was canceled:
| Input | Parameter Specification |
|---|---|
| Release | Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Reason | Optional. A key named reason with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Restore Release
POST or PUT /api/releases/restore
Returns a status of 200 if the release was restored:
| Input | Parameter Specification |
|---|---|
| Release | Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Get Builds
GET or POST /api/releases/builds
Returns a status of 200 and a body with an array of build objects based on the specified optional filter parameters:
| Filter | Parameter Specification |
|---|---|
| Application | Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release | Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value. |
| Build | Either a key named buildId with an integer value, or a key named buildNumber with any value. |
| Pipeline | A key named pipelineName with any value. |
| Stage | A key named furthestStage with any value. |
| Status | A key named status with a value of active, rejected, or deployed. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Create Build
POST or PUT /api/releases/builds/create
Returns a status of 200 and a body with a build object that was created with the following input parameters:
| Input | Parameter Specification |
|---|---|
| Release | Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Build Number | Optional. A key named buildNumber with any value; if not specified, the build number will be automatically generated. |
| Variables | Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Get Deployments
GET or POST /api/releases/builds/deployments
Returns a status of 200 and a body with an array of deployment objects based on the specified optional filter parameters:
| Filter | Parameter Specification |
|---|---|
| Application | Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| Release | Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value. |
| Build | Either a key named buildId with an integer value, or a key named buildNumber with any value. |
| Deployment | A key named deploymentId with an integer value. |
| Pipeline | A key named pipelineName with any value. |
| Stage | A key named pipelineStageName with any value. |
| Environment | Either a key named environmentId with an integer value, or a key named environmentName with any value. |
| Status | A key named status with a value of pending, executing, succeeded, warned, or failed. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Deploy Build
POST or PUT /api/releases/builds/deploy
Returns a status of 200 and a body with an array of deployment objects that were created with the following input parameters:
| Input | Parameter Specification |
|---|---|
| Build | Required. Either a key named buildId with an integer value, or a key named buildNumber with any value. |
| Release | Required if buildNumber is specified, otherwise must not be set. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value. |
| To Stage | Optional. A key named toStage with any value. If not supplied, the next stage in the pipeline will be used. |
| Force | Optional. A key named force with a value of true or false. |
| Start Time | Optional. A key named startTime with a timestamp of when the deployment should start. If not supplied, the deployment will start immediately. If the timestamp does not contain a date, it defaults to today. If a date is specified without a time, it defaults to midnight. If there is no time zone specified, it defaults to the server's local time zone. Available in BuildMaster 6.0.2+ |
| Variables | Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Reject Build
POST or DELETE /api/releases/builds/reject
Returns a status of 200 if the build was rejected:
| Input | Parameter Specification |
|---|---|
| Build | Required. Either a key named buildId with an integer value, or a key named buildNumber with any value. |
| Release | Required if buildNumber is specified, otherwise must not be set. Either a key named releaseId with an integer value, or a key named releaseNumber with any value. |
| Application | Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value or a key named applicationName with any value. |
This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.
Was this article helpful?
