Create New Release via REST API

If you want to automate Release—for example, to trigger a release or pipeline run from an upstream system—the Release REST API is good way to do so. This topic describes how to use cURL or PowerShell to start a new release based on a release template.

Find the template ID

Before using the API, you need to know the ID of the release template. You can find this in the URL for the template itself. For example:

For more information about template IDs, refer to How to find IDs.

important

In the API call itself, you must always prepend the template ID with Applications/ for technical reasons.

Using cURL

The /api/v1/templates/{templateId:.*?}/start API call creates a release from a template and immediately starts it. For the simple template in this example, the cURL command to create the release would be:

curl -u 'admin:secret'  -v -H "Content-Type: application/json" http://localhost:5516/api/v1/templates/Applications/Release2994650/start -i -X POST -d '{"releaseTitle": "My Automated Release", "folderid": "My folder"}'

note

As of version 8.2.0, the optional parameter folderid can be used to indicate the folder where to create the release. The folderid value can be null when you create a release on global level, or the same folder as the template the release is created from.

The response to the API contains the ID of the release that was created. For example:

{"id":"Release1624834", ...}

Start a release with variables

A more complex example that includes the setting of variables would look like this:

curl -u 'admin:admin' -v -H "Content-Type: application/json" http://localhost:5516/api/v1/templates/Applications/Release612654/start -i -X POST -d '{"releaseTitle": "My Automated Release", "releaseVariables": {"${version}": "1.0", "${name}": "John"}}'

Security when using cURL

To explicitly allow cURL to perform "unsecure" SSL connections and transfers, add this to the cURL command:

-sslv3 -k

To use a certificate, add this to the cURL command:

-sslv3  --cacert /path/to/certificate

If you created a keystore when installing Release, use this command to extract the certificate:

keytool -exportcert -rfc -alias jetty -keystore conf/keystore.jks -file conf/cert.crt

Using PowerShell

This example shows how you can use PowerShell to automatically create and start a release based on a template with the ID Release293292865:

$body = @{
    "releaseTitle" = "My Automated Release"
}

$json = $body | ConvertTo-Json
$headers = @{
"Authorization" = "Basic YWRtaW46YWRtaW4="
}

Invoke-RestMethod -Headers $headers -ContentType "application/json" -Body $json -Method Post -Uri "http://samplehost:5516/api/v1/templates/Applications/Release293292865/start"