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.

Releases typically use staged workflows to organize deployment phases and deployer workflows to coordinate component deployments within each stage.

An application release includes:

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 can call 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.

Prerequisite steps for creating a release

Complete each of the following steps before creating an application release. A release can contain more than one of each object listed, as long as all are properly referenced in the deployer workflow.

Create a component that contains a traceable artifact version.

Use either of the following to create an artifact version:
- Run a build workflow.
- Add the version manually in the UI.
Create an application that is associated with:
- The component containing the above artifact version.
- An environment to deploy to.
Create a deployer workflow and reference it in a staged workflow. This sets up connected release stages and enables component orchestration via the deployer.

Once you have completed the above steps, you can create a release with the staged workflow and a defined manifest.

Release requirements

To fully configure an application release for execution, you must complete the following:

Each prerequisite step.
Create a release that includes a manually-triggered application workflow and a string-parameter manifest.

Access releases

Create and manage releases for an application in Releases. Releases displays the following information about 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.
The release creation date and time.

To access releases:

Select an organization, and then select Applications.
Select an application.
Select Releases.
(Optional) Filter releases by status.
(Optional) Search for a specific release by entering all or part of a release name into Search.

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

Figure 1. Example started 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 above, 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.

You can add workflow parameters as input on the Create release panel.

Figure 3. Create release

Select Define manifest.
(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 (/).
Do either of the following:
- Select a Version from the options for each artifact selected to be in the manifest.
- Manually enter a version.
  
  If you enter a version that does not exist, is displayed, and the application release cannot be started.
  
  Figure 4. Selecting two artifacts for the manifest definition.
Select Next.
Select Create. The release is listed in Releases with its current status.

Figure 5. Release definition

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.

Delete a closed release

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

You must first close a release before you can delete it. You must have the appropriate permissions to delete a release.

To delete a release:

Access Releases for your selected application.
Select next to the closed release you want to delete.
Select Delete.
Select Delete release.

The closed release is permanently deleted and removed from the list of Releases.

View the audit report

An audit report is associated with the most recent run of a release, and it provides a comprehensive overview of the run, including all approvals, deployments, and job evidence. The audit report can be important in maintaining regulatory compliance. You can also download the report as a PDF file.

The audit report includes these sections:

Definition
Approvals
Deployments
Evidence

Figure 6. Audit report

To view the audit report for a release:

Access Releases for your selected application.
Select next to the chosen release to view each section of the audit report, as follows:
- The Audit report Definition displays with key release metadata, including:
  - The release name and description.
  - The associated workflow.
  - Input parameters, such as environment or manifest inputs.
  - Manifest content, including the component artifacts selected for deployment.
    
    View the audit report Definition
    
    Figure 7. Audit report definition

Select the section to view.
1. Audit report Approvals to view the release run’s manual approval information, including the:
  - Stage.
  - Job name.
  - Approval status.
  - Approver name.
  - Approval comment.
  - Associated parameters, if applicable.
  - Approval date.
    
    View the audit report Definition
    
    Figure 8. Audit report approvals

Select Audit report Deployments to view the release run’s deployed artifact information, including links to each:
- Deployed artifact name and version.
- Environment.
- Component.
- Run that published the artifact.
  
  View the audit report Definition
  
  Figure 9. Audit report deployments
Select Audit report Evidence to view the release run’s generated evidence, including:
- The associated job name.
  
  View the audit report evidence
  
  Figure 10. Audit report evidence
(Optional) Select Download report to download a PDF file of the full audit report.

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-78ab-90cd-ef7812345678",
    "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-7890abcdef90"
    }
  },
  "componentName2": {
    "deploy": true,
    "id": "efab1234-ef56-ab78-cd90-1234ef125678",
    "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-5678-1234-56781234abcd",
    "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.

An example 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:
          artifact-id: ${{ fromJSON(inputs.manifest)['frontend-c']['frontend-art'].id }
          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:
          artifact-id: ${{ fromJSON(inputs.manifest)['backend-c']['backend-art'].id }}
          target-environment: pre-prod▼

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