api-reference.md

API Reference

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.

{% tabs %} {% tab title="201" %}

{% endtab %}

{% tab title="400" %}

{
  "error": "Invalid release candidate version"
}

{% endtab %}

{% tab title="400" %}

{
  "error": "Invalid commit hash"
}

{% endtab %}

{% tab title="404" %}

{
  "error": "GitHub repository not found"
}

{% endtab %} {% endtabs %}

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.

{% tabs %} {% tab title="201" %}

{% endtab %}

{% tab title="400" %}

{
  "error": "Invalid release candidate version"
}

{% endtab %}

{% tab title="404" %}

{
  "error": "Release environment not found"
}

{% endtab %}

{% tab title="404" %}

{
  "error": "Release not found"
}

{% endtab %} {% endtabs %}

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.

{% hint style="info" %} This method does not trigger the configured deployment workflow. {% endhint %}

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 - failure - canceling - canceled - unknown

Response

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

{% tabs %} {% tab title="200" %}

{% endtab %}

{% tab title="400" %}

{
  "error": "Invalid release candidate version"
}

{% endtab %}

{% tab title="404" %}

{
  "error": "Release environment not found"
}

{% endtab %}

{% tab title="404" %}

{
  "error": "Release not found"
}

{% endtab %} {% endtabs %}