API Reference for Releases

This reference page describes the usage of REST API for Release management. Get instructions on how to create a release, create and update deployment, and more.

This document describes the usage of REST API for Release management. You can also use GraphQL API for composite queries.

Create a Release

POST /api/releases/<project_name>/releases/<release_candidate_version>

This creates a new Release and an associated Release Candidate with the provided commit SHA.

Parameters

Name	Description
project_name	Name of the Release Project. Case sensitive.
release_candidate_version	Release candidate version string represented as: release-version-rcX when X is an integer. Note that -rcX is a required suffix for a validate release candidate version.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
repo	String	Repository associated with the Release. String of the format: org/repo_name
commit	String	Head commit SHA to cut a release at.
trigger_build_workflow	Boolean. Optional	If set to true, it will start a build action that is configured in the settings. When set to false, the release candidate is created and marked as ready without triggering the build action. Default is false.

Response

If successful, HTTP 201 response is returned back.

201

400

400

404

Create a Deployment

POST /api/releases/<project_name>/environments/<env_name>/deployments

This creates a new Deployment for the provided Release Candidate and Environment. This workflow will also trigger the appropriate deployment workflow configured for that environment.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Parameters

Name	Description
project_name	Name of the Release Project. Case sensitive.
env_name	Name of the Environment within the Release Project. Case sensitive.

Body

Name	Type	Description
release_candidate_version	String	Release candidate version associated with the Release Candidate that will be deployed. String represented as: release-version-rcX when X is an integer. Note that -rcX is a required suffix for a validate release candidate version.

Response

If successful, HTTP 201 response is returned back.

201

400

404

404

Update Deployment status

PATCH /api/releases/<project_name>/environments/<env_name>/deployments

Update the status of the Deployment once it's created. If a Deployment doesn't already exist for the given Release Candidate version and the Environment, a new deployment is also created.

This can be used for a custom CD pipeline to send the deployment status to Aviator.

This method does not trigger the configured deployment workflow.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Parameters

Name	Description
project_name	Name of the Release Project. Case sensitive.
env_name	Name of the Environment within the Release Project. Case sensitive.

Body

Name	Type	Description
release_candidate_version	string	Release candidate version associated with the Release Candidate that will be deployed. String represented as: release-version-rcX when X is an integer. Note that -rcX is a required suffix for a validate release candidate version.
status	string	Possible values: - pending - in_progress - success - failure - canceling - canceled - error - unknown

Response

If successful, HTTP 200 response is returned back. The API returns a 200 response even when a new deployment is created.

200

400

404

404

List deployments

GET /api/releases/<project_name>/environments/<env_name>/deployments

List recent Deployments for a given Environment. Results are paginated and ordered by most recent first.

Headers

Name	Value
Authorization	Bearer <token>

Parameters

Name	Description
project_name	Name of the Release Project. Case sensitive.
env_name	Name of the Environment within the Release Project. Case sensitive.

Query Parameters

Name	Type	Description
page	Integer. Optional	Page number for pagination. Defaults to 1.
per_page	Integer. Optional	Number of results per page. Defaults to 10. Maximum 100.

Response

If successful, HTTP 200 response is returned back.

200

[
    {
      "actor": "User email or None",
      "deploy_end_at": "The timestamp that the deployment process ended at.",
      "deploy_start_at": "The timestamp that the deployment process started at.",
      "environment_name": "Release environment name",
      "error_message": "Error message associated with the deployment, or null.",
      "from_release_candidate_version": "The RC version of the previous release that this environment is transitioning from or None",
      "from_release_version": "The version of the previous release that this environment is transitioning from or None",
      "id": "Deployment id",
      "release_candidate_version": "Deployment release candidate version",
      "release_version": "Deployment release version",
      "status": "The status of the deployment."
    },
    ...
]

404

404

Rollback

POST /api/releases/<project_name>/environments/<env_name>/rollback

Roll back an Environment to a previous Release Candidate. If the most recent deployment was successful, the environment is rolled back to the version that was running before it. If the most recent deployment failed, the last known successful version is re-deployed. Any active deployments are canceled before the rollback is triggered.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Parameters

Name	Description
project_name	Name of the Release Project. Case sensitive.
env_name	Name of the Environment within the Release Project. Case sensitive.

Body

Name	Type	Description
force	Boolean. Optional	If set to true, allows rollback even when the environment is frozen. Default is false.

Response

If successful, HTTP 201 response is returned back with the created deployment.

201

{
  "actor": "User email or null",
  "deploy_end_at": null,
  "deploy_start_at": "ISO 8601 timestamp of when the deployment was triggered.",
  "environment_name": "Release environment name",
  "error_message": null,
  "from_release_candidate_version": "The RC version of the release this environment is transitioning from, or null",
  "from_release_version": "The version of the release this environment is transitioning from, or null",
  "id": "Deployment id",
  "release_candidate_version": "Deployment release candidate version",
  "release_version": "Deployment release version",
  "status": "pending"
}

400

404

404

404