Client API: Deployment servers: Releases

Part of Deployment servers.

GET /api/v1/client/servers/{uuid}/releases

List the server's releases.

Newest first, with what the server clones. git is the repository (never with a credential), its branch, whether a repository token is set (token_set) and whether releases apply (releases); when they do not, reason says why, and git is null for a server that clones nothing. can.deploy says whether a release may start now, with the error and reason when not. current_release is the live release and in_flight the one on its way, each null when there is none.

Each release has status (queued, building while the commit is fetched, deploying, ready, failed, canceled or superseded), trigger (manual, rebuild, rollback or install), source (git, redeploy or rollback), the commit (git_ref, git_sha, commit_message, commit_author), is_current, can_rollback, can_cancel, and for a failed one error, error_code and restored (true when it had changed files and the previous version was put back). Needs software.read.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/servers/{uuid}/releases

Deploy a commit to the server.

Starts a release of the newest commit of the server's branch, or of the branch, tag or commit git_ref names. The platform fetches and checks the commit before the server is touched. The server then stops, the repository's files are replaced, and it starts again when it was running. If it does not stay up, the previous version is put back. Files the repository does not hold are left alone. When the server already runs that commit, the release ends canceled with error_code already_current and nothing changes.

Answers 201 with the queued release. 409 with error no_git_source (the server clones nothing the platform can fetch), release_in_progress, server_busy (installing, transferring, restoring or suspended), install_in_progress, snapshot_in_progress or server_locked; 422 invalid_ref for a git_ref that is not a branch, tag or commit name. Needs software.update.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json

GET /api/v1/client/servers/{uuid}/releases/{release_uuid}

Read one release with its log.

log holds each step it took, what it left out and, for one that failed to start, the server's last output. origin is the release whose stored files a rollback or a redeploy runs. A release of another server answers 404. Needs software.read.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/servers/{uuid}/releases/{release_uuid}/cancel

Cancel a release before it changes the server.

A release that is queued or still being fetched can be cancelled. Nothing on the server has changed at that point. 409 not_cancelable for one that is replacing files (it finishes, or puts the previous version back, on its own), one that has ended, and the release an install makes. Needs software.update.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/servers/{uuid}/releases/{release_uuid}/rollback

Roll the server back to an earlier release.

Starts a release of the earlier release's stored files. Nothing is fetched from the git host, so it works while the host is down or the token has expired.

Answers 201 with the new release (trigger rollback). 409 already_current for the live release, not_rollbackable for one that was never live, archive_not_stored for one whose files are no longer kept (deploy its commit instead), and the refusals of Deploy. Needs software.update.

Authentication: an access token, sent as Authorization: Bearer <token>.