Releases

In the CloudBees platform, an application release represents the artifact versions within that application and the workflow used to deploy those artifacts.

Prerequisites

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

An application associated with with one or more components.
At least one application component that contains a build workflow used to generate and register artifact versions.
An application 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.

Releases list

Manage application releases by accessing the details of an application.

Use the to select an organization or sub-organization.
Select Applications from the left menu.
Select the application name or APPLICATION DETAILS link. The details for the application display.
Select the Releases tab. A list of releases for the application display.

Figure 1. Releases

Manage releases.
- Navigate to applicable data and features using the breadcrumb menus and links.
- Access the Git repository linked to the release by selecting the repository name link.
Access release data.
- Filter list by Status.
- Use the search to locate specific releases.
- Sort the releases data by column.
- View details for a specific release by selecting the release name or release workflow name link.
- Modify release workflow in the Composer by selecting the workflow name link.
Use these release-related features.
- Configure a new release by selecting Create release.
- Modify an existing release by selecting Edit from the release options.
- Start a new release workflow run by selecting .
- Delete an existing release by selecting Delete from the release options.

Configure a release

To configure an application release.

Access release configuration features via: the Releases list.
View access steps
1. Use the to select an organization or sub-organization.
2. Select Applications from the left menu.
3. Select the application name or APPLICATION DETAILS link. The details for the application display.
4. Select the Releases tab. A list of releases for the application display.
5. Create a new or edit existing release.
  
  Configure a new release by selecting Create release.
  
  Modify an existing release by selecting Edit from the release options.
Access release configuration features via: the Release details.
View access steps
1. Use the to select an organization or sub-organization.
2. Select Applications from the left menu.
3. Select the application name or APPLICATION DETAILS link. The details for the application display.
4. Select the Releases tab. A list of releases for the application display.
5. Create a new or edit existing release.
  
  Configure a new release by selecting Create release.
  
  Modify an existing release by selecting Edit from the release options.

Figure 2. Edit release

Use these features to configure a release.

Configure release.
- Enter unique identifier for the release in the Release name field.
- Select the workflow to run the release.
Define the release manifest.

Figure 3. Define manifest
1. Use these features to manage artifacts in the manifest.
  - Filter list by artifact name.
  - Use the search to locate artifacts.
2. Manage manifest artifacts.
  - Add a new artifact.
    
    Use filter and search to locate an artifact.
    
    Choose the artifact version from the Version options.
    
    Enable the artifact checkbox to include the artifact in the manifest.
    
    Click the Select to save changes.
  - Remove an artifact from the manifest.
    
    Disable the artifact checkbox.
    
    Click the Select to save changes.

Release details

Use the Release details features to access information and functions related to a releases run.

To access details for a release: Access a list of runs for an organization.

An organization or sub-organization.
View access steps
Navigate to the Runs list of an organization, sub-organization, application, or component.

Figure 4. Releases details

Use these release-related features to:
- Navigate to applicable data and features using the breadcrumb menus and links.
- Access release workflow Runs list features and information by selecting Runs.
- End the release by selecting Close.
- Start or restart the release selecting Run workflow.
- Modify an existing release by selecting Edit from the release options.
- Delete an existing release by selecting Delete from the release options.
Access release data:
- The Git repository linked to the release by selecting the repository name link.
- List of artifacts in the component by selecting the artifact name link.
- The Component summary for the application component.
- List full deployment history for the artifacts.

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.

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

Application release manifest example

{
  "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.

Usage example

In the example below, the system-generated JSON data of the application release manifest is accessed and utilized by the release workflow.

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

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.

Example of a typical release workflow.

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.