Create and Promote a Release

One common use case of the Vendor API is to connect it into your CI/CD workflow and create new unstable releases on Replicated whenever a new build is run. This is especially helpful when you pair it with the ability to script the installation of Replicated for automated testing. This article will show you how to use the Vendor API to automatically create a new release and promote it to the unstable channel.

Prerequisites

You should already have an API Token from the vendor site, and you should know the target App ID and Channel ID. For details on how to get the App ID and Channel ID programmatically, check out the Vendor API documentation. These values will not change and should be supplied as static values to your deployment script.

Next, you should have the YML that you want to promote. One common method to generate this is to store the YML with template values indicating the image tags to use. When your build server creates a new Docker image, it’s easy to generate a new YAML programmatically.

Create a new release

First, we will create a new release with the current YAML. This release will not be connected to your Channel ID at all; we are simply creating a release in your app that can be promoted later. T his can be done with a single POST:

curl -X POST \
     -H 'Authorization: <API_Token>' \
     -H 'Content-Type: application/json' \
     -d '{"source":"latest"}' \
     https://api.replicated.com/vendor/v1/app/<AppID>/release

Note, in the result, you will receive a JSON object that contains a key named Sequence. Save this value. This is the unique ID for the release you are creating. It will be required in the next steps.

Update the release

Next, we want to put our new YML into this release. This is accomplished with a single PUT:

curl -X PUT \
     -H 'Authorization: <API_Token>' \
     -H 'Content-Type: application/yaml' \
     -d <YAML CONTENTS> \
     https://api.replicated.com/vendor/v1/app/<AppID>/<Sequence>/raw

There will be a 204 No Content status code returned if this is successful. If there are parsing or validation errors in the YML, a detailed message will be returned.

Promote the release

Finally, we want to promote this release to the channel. This will make it immediately available to any installation of a license from that channel. We recommend doing this for the Unstable or dev/test channels only at this time. Promoting the release is a single POST:

curl -X POST \
     -H 'Authorization: <API_Token>' \
     -H 'Content-Type: application/json' \
     -d '{"channels":["<ChannelID>"],\
          "release_notes":"This is an auto generated release",\
          "label":"AUTO","required":false}' \
     https://api.replicated.com/vendor/v1/app/<AppID>/<Sequence>/promote

This release will be generated with static release notes and version label, but these fields can be edited manually at any time, including when you promote to the beta channel.

Test Your App YAML Changes

When creating new releases during an automated process we recommend testing your app YAML first. This will allow you to validate, and if there are errors during validation exit your build process prior to creating a new release sequence.

To validate your app YAML we use the same call as updating but with a dry_run flag. This will allow you find any errors without updating your application. On success the response will be HTTP 200 OK. If there is a problem with your app YAML the service will return a HTTP 400 response with a JSON payload indicating the error. A HTTP 403 response indicates that the sequence you’re trying to update has already been promoted in which case you would create a new release and retry the dry run.

curl -X PUT \
     -H 'Authorization: <API_Token>' \
     -H 'Content-Type: application/yaml' \
     -d <YAML CONTENTS> \
     https://api.replicated.com/vendor/v1/app/<AppID>/<Seq>/raw?dry_run=1

Next Steps

Once you have this integrated into your CI/CD process, the next step is to set up automated installation for testing and you will be close to a fully automated on-prem deployment process.