Releases #

A release is a version of a project, cut from the release branch of one of its environments. The console does not build anything at this stage: it dispatches the release.yml workflow of the project's GitHub repository on that branch, where semantic-release computes the version, creates the Git tag and the GitHub Release. The console follows the workflow run and records the version it produced.

A release is then deployed to one or more environments.

Controller: org-release

Base HTTP route:

/_/organizations/:organizationId/projects/:projectId/releases

Releases are scoped to a project. Any project member can cut and read releases; an external collaborator can only read them. See the Continuous deployment guide for the repository side.

Cut a release #

Dispatches the repository's release.yml workflow on the branch mapped to environmentId, and returns the release document right away. The version is not known yet: follow the release with refresh until its run completes.

const release = await kuzzle.query({
  controller: 'org-release',
  action: 'create',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/releases?environmentId=production

Requirements:

• the project is connected to a GitHub repository (see Projects);
• the environment has a release branch mapped (see Release branch and tier);
• the repository has a release.yml workflow that can be dispatched (workflow_dispatch) and accepts a console_dispatch_id input.

Refresh a release #

Reads the workflow run and updates the release: run status and conclusion and, once the run has succeeded, the version, channel and changelog of the GitHub Release it produced. Idempotent and safe to poll. Once the release has an outcome, it no longer changes.

const release = await kuzzle.query({
  controller: 'org-release',
  action: 'refresh',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  releaseId: '<release-id>'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/releases/:releaseId/_refresh

outcome settles to:

• released: the run succeeded and produced a version;
• no-release: the run succeeded but semantic-release found no releasable commit, so no version was cut;
• failed: the run did not succeed (releaseRun.conclusion says how).

List releases #

Lists the releases of a project, most recent first.

const releases = await kuzzle.query({
  controller: 'org-release',
  action: 'list',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project'
});

HTTP route:

GET /_/organizations/:organizationId/projects/:projectId/releases

Get a release #

const release = await kuzzle.query({
  controller: 'org-release',
  action: 'get',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  releaseId: '<release-id>'
});

HTTP route:

GET /_/organizations/:organizationId/projects/:projectId/releases/:releaseId

See Data models for the shape of a release.