Releases

In software delivery, an application release is a versioned collection of specific binaries and configuration files that are deployed to a live environment. In the CloudBees platform, create and manage releases for your applications. Monitor release status, run releases, and close releases that are no longer needed.

A CloudBees platform application release is composed of the following elements:

Manifest: The set of component artifact versions that are part of the application to be released.
Workflow: The application workflow that encapsulates the logic for orchestrating the release. The workflow may delegate to component workflows that deploy specifically to different application environments.
Metadata: The release information, including the software version, release author, release notes, dependencies, environment information, and target completion date.

The CloudBees application release runtime information is the data tracked during a running release workflow, and includes:

Workflow runs: This usually refers to the last run of the workflow that ran in the context of the release.
Actual payload: The resolved application manifest used by each workflow run.
Approvals granted: The approvals, if any, required for the workflow runs to complete successfully.
Evidence published: The evidence, if any, published in conjunction with the workflow runs.
Deployments: The deployment data for the release.
Environment inventory: The list of environments used in the release.

Release requirements

To fully configure an application release for execution, the following must be in place:

An application associated at with least one component.
At least one component that contains a build workflow used to generate and register artifact versions.
A component that contains a deployment workflow, or a shared workflow that accepts an artifact name and version as inputs.
A manually-triggered application workflow with a string-parameter manifest.

Access releases

Create and manage releases for an application in Releases.

Releases displays the following for each release:

Name: Select to view the release definition and the run summaries for the release.
Status: The release status.
Workflow: Select to view the associated workflow in the Workflow composer.
Last run: Select to view Run details of the last workflow run.

From Releases, you can create, run, update, and close releases.

To access releases:

Select an organization, and then select Applications.
Search or filter as necessary to select the application you want, by selecting either its Name or APPLICATION DETAILS.
Select Releases.

The releases for the selected application are displayed. Select a release name to view the release details.

Figure 1. Example release highlighted in Releases.

Release details

Select a release Name in Releases to display release information, including:

The release definition.
A summary of all runs.

Figure 2. Example release definition.

As in the example below, the release information includes:

Top navigation linking back to Releases.
The release status.
Select any of the following options:
- Close to close a release.
- Run workflow to run or rerun the workflow.
- , and then Edit, to update the release definition.
Tab between the release Definition and a summary of Runs.
Select the branch name/workflow name to view it in the Workflow composer.
Select any of the links in the manifest, including:
- A list of the artifact versions.
- The component summary for the release application.
- The current release version details.

Create a release

Create a release in your application to deliver your software efficiently using the CloudBees platform. If you do not have all necessary release requirements, you can still save a Draft release definition.

To create a release definition:

Access Releases for your selected application.
Select Create release.
Enter a Release name.
(Optional) Enter a Description.
Select a workflow from the options.
You may only select a single workflow, and it must contain:

A manifest input parameter.

A workflow_dispatch trigger.
Select Define manifest.

Figure 3. Example release with Define manifest highlighted.
(Optional) Select Filter to filter by artifact name, or enter all or part of an artifact name to Search for specific artifacts.
Select next to an artifact name to add it to the manifest (). You can add an unlimited number of artifacts.

Select or deselect all listed artifacts at once with the table header (/).
Select a Version from the options for each artifact selected to be in the manifest.

Figure 4. Selecting two artifacts for the manifest definition.
Select Next.
Select Create.

The release definition is created accordingly, and the release is listed in Releases with its current status. The release status depends on whether all requirements are present in the release.

Release status

The status for a release is listed next to the release name in Releases. If all requirements for a release to be run are met, the release is marked Ready to run. If you have a created a release without an associated valid release workflow or a defined manifest, the release is marked Draft. Update a Draft release with any missing requirements to change the status to Ready to run.

Table 1. Release status definitions.
Release status	Definition
Draft	Release is missing one or more requirements.
Ready to run	Release has all requirements in place and can be run.
Pending start	Release is in the process of executing a workflow run for the first time.
Started	Release has executed at least one workflow run.
Closed	Release is closed permanently.

Run a release

Run any release whose status is Ready to run. You can also rerun any release if is enabled.

To run or rerun a release:

Access Releases for your selected application.
Select next to the release you want to run.

If is displayed, the release cannot be executed.

The release status is changed to Pending start or Started and the release is executed.

You can also select Run workflow in the release details screen to run a workflow.

Run is disabled

If is displayed next to a release, you cannot run it. Hover over to get an explanation of why the release cannot be run.

Some common reasons for why a release cannot be run include:

The release is not in Ready to run or Started status.
A workflow run is starting or already running.
The release status is updating.

Update a release

Update the definition of any release whose status is Draft, Ready to run, or Started.

You cannot update the definition of a release that is closed or in the process of closing.

To update a release configuration:

Access Releases for your selected application.
Select next to the release you want to update.
Select Edit, and then perform one or more of the following:
- Update the Release name.
- Select a different workflow from the options.
- Select Edit manifest to update the manifest, and then select Next.
Select Save.

The release configuration is updated accordingly.

Close a release

Close any releases that are no longer needed. This action is irreversible, and you can no longer update or run a release that has been closed.

To close a release:

Access Releases for your selected application.
Select next to the release you want to close.
Select Close.
Select Close release.

The release configuration status is permanently changed to Closed in Releases. Once a release is in closing or fully closed status, it cannot be updated or run, and any runs currently in process are terminated.

The release manifest

Release manifests exist to ensure that releases are deployed with the correct artifact versions to the appropriate software environment, and are helpful in troubleshooting release issues.

The CloudBees platform application release definition includes a release manifest that specifies artifact versions from the components that are deployed as part of the release. This release manifest is passed as JSON string data to the release workflow in the manifest input parameter.

Key aspects of the manifest format:

The manifest JSON is grouped by component.
A deploy flag is set at both the component level and at each of the artifact levels, to indicate if they are part of the release manifest.
- Use this flag in the workflow to dynamically control whether the component and artifact-specific jobs/steps are invoked.
- "deploy": true is specified for a component if at least one artifact of the component is part of the release manifest. Otherwise, it is set to false.
- "deploy": true is specified for an artifact if it is part of the release manifest. Otherwise, it is set to false.

Component names may not always be unique, so refer to the following when configuring a release:

CloudBees only guarantees component name uniqueness within a given tenant organization.
If multiple components in the same application do have the same name, the component ID is used to group the component artifacts, instead of the component name.

Example application release manifest JSON file.

In the following release manifest example, these artifact versions are specified as released:

artifactName2@v1.4 of componentName1 component
artifactName3@v1.2.2.4 of componentName2 component
artifactName5@v11.22 of componentName3 component

And these artifact versions are specified as not released:

artifactName1 of componentName1 component
artifactName4 of componentName2 component

Example manifest JSON file.

{
  "componentName1": {
    "deploy": true,
    "id": "abcd1234-56ef-78gh-90ij-klmn1234opqr",
    "artifactName1": {
      "deploy": false,
      "version": "n/a",
      "url": "n/a",
      "digest": "n/a"
    },
    "artifactName2": {
      "deploy": true,
      "version": "1.4",
      "url": "docker.io/myApplication/artifactName2:1.4",
      "digest": "abcd1234-ab12-cd34-ef56-7890ghijklmn"
    }
  },
  "componentName2": {
    "deploy": true,
    "id": "efgh1234-ef56-gh78-ij90-1234opqr5678",
    "artifactName3": {
      "deploy": true,
      "version": "1.2.2.4",
      "url": "docker.io/myApplication/artifactName3:1.2.2.4",
      "digest": ""
    },
    "artifactName4": {
      "deploy": false,
      "version": "n/a",
      "url": "n/a",
      "digest": "n/a"
    }
  },
"componentName3_https://github.com/myOrg/myRepo.git": {
    "deploy": true,
    "id": "78901234-abcd-lmno-1234-pqrs1234tuvw",
    "artifactName5": {
      "deploy": true,
      "version": "11.22",
      "url": "docker.io/myApplication/artifactName5:11.22",
      "digest": ""
    }
  }
}▼

Dynamic control of deployment

The deploy flag can be used in the workflow to dynamically control the deployment of the component in an if condition, as in the following example.

Example workflow with conditionals implemented.

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: app-deployer
on:
  workflow_dispatch:
    inputs:
      manifest: (1)
        type: string
        required: true
      environment:
        type: string
        required: true
jobs:
  job-component1:
    if: ${{ fromJSON(inputs.manifest)['component1'].deploy }}(2)
    uses: myOrg/component1/.cloudbees/workflows/deploy.yaml
    with:
      manifest: ${{ toJSON(fromJSON(inputs.manifest)['component1']) }}(3)
      environment: ${{ inputs.environment }}▼

1	This `manifest` input is required for a release workflow.
2	This condition defines whether the `job-component1` job that is responsible for deploying the `component1` component will be called depending on the `deploy` flag specified for the component in the deployment manifest.
3	This code specifies the format of the manifest release.

Release workflow example

The system-generated JSON data of the application release manifest is accessed and utilized by the release workflow.

In a typical release workflow such shown below, each manifest entry (artifact version) invokes a deployment operation and registers it with the Register an artifact deployed to an environment action.

Example of a release workflow.

In this example:

The application contains components named frontend-c and backend-c.
The frontend-c component contains an artifact frontend-art.
The backend-c component contains an artifact backend-art.

A typical release workflow YAML file.

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Single-stage release workflow
on:
  workflow_dispatch:
    inputs:
      manifest: (1)
        type: string
        required: true
jobs:
  Front-end:
    if: ${{ fromJSON(inputs.manifest)['frontend-c']['frontend-art'].deploy }}
    steps:
      - name: Deploy Front-end
        kind: deploy
        uses: cloudbees-io/register-deployed-artifact@v1
        with:
          name: frontend-art
          version: ${{ fromJSON(inputs.manifest)['frontend-c']['frontend-art'].version }}
          url: ${{ fromJSON(inputs.manifest)['frontend-c']['frontend-art'].url }}
          digest: ${{ fromJSON(inputs.manifest)['frontend-c']['frontend-art'].digest }}
          target-environment: pre-prod
  Back-end:
    if: ${{ fromJSON(inputs.manifest)['backend-c']['backend-art'].deploy }}
    steps:
      - name: Deploy Back-end
        kind: deploy
        uses: cloudbees-io/register-deployed-artifact@v1
        with:
          name: backend-art
          version: ${{ fromJSON(inputs.manifest)['backend-c']['backend-art'].version }}
          url: ${{ fromJSON(inputs.manifest)['backend-c']['backend-art'].url }}
          digest: ${{ fromJSON(inputs.manifest)['backend-c']['backend-art'].digest }}
          target-environment: pre-prod▼

1	This `manifest` input is required for a release workflow.