Release management reference

Technical specifications for release statuses, manifest format, and deployer workflow structure in CloudBees Unify.

Release statuses

Table 1. Release status definitions
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.

Update a Draft release with any missing requirements to change its status to Ready to run.

Release manifest format

The release manifest specifies which artifact versions are deployed as part of a release. It 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 for each artifact in each component. Use this flag in the workflow to dynamically control whether artifact-specific jobs are invoked. "deploy": true indicates the artifact is part of the release manifest; otherwise it is set to false.

Component names may not always be unique. CloudBees Unify only guarantees component name uniqueness within a given tenant organization. If multiple components in the same application have the same name, the component ID is used to group component artifacts instead of the component name.

Example manifest JSON structure

{
  "componentName1": {
    "artifactName1": {
      "deploy": true,
      "id": "abcd1234-ab12-cd34-ef56-7890abcdef90"
    }
  },
  "componentName2": {
    "artifactName2": {
      "deploy": false,
      "id": ""
    },
    "artifactName3": {
      "deploy": true,
      "id": "pqrd1234-ab12-cd34-ef56-7890abcdef90"
    }
  }
}▼

The manifest JSON structure no longer includes these fields: artifact block (name, version, url, digest) and component block (deploy, id). To retrieve artifact details including name, version, URL, and digest, refer to Register and track artifacts.

The deploy flag can be used with an if condition in a deployer workflow to dynamically control deployment:

Example deployer workflow using the deploy flag

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: app-deployer
on:
  workflow_call:
    inputs:
      manifest: (1)
        type: string
        required: true
      environment:
        type: string
        required: true
jobs:
  deploy-componentName1-artifactName1:
    if: ${{ fromJSON(inputs.manifest)['componentName1']['artifactName1'].deploy }} (2)
    uses: myorg/componentName1/.cloudbees/workflows/deploy.yaml
    with:
      artifact-id: ${{ fromJSON(inputs.manifest)['componentName1']['artifactName1'].id }}
      environment: ${{ inputs.environment }}
  deploy-componentName2-artifactName2:
    if: ${{ fromJSON(inputs.manifest)['componentName2']['artifactName2'].deploy }}
    uses: myorg/componentName2/.cloudbees/workflows/deploy.yaml
    with:
      artifact-id: ${{ fromJSON(inputs.manifest)['componentName2']['artifactName2'].id }}
      environment: ${{ inputs.environment }}
  deploy-componentName2-artifactName3:
    if: ${{ fromJSON(inputs.manifest)['componentName2']['artifactName3'].deploy }}
    uses: myorg/componentName2/.cloudbees/workflows/deploy.yaml
    with:
      artifact-id: ${{ fromJSON(inputs.manifest)['componentName2']['artifactName3'].id }} (3)
      environment: ${{ inputs.environment }}▼

1	The `manifest` input is required for a release workflow.
2	This condition controls whether the job is executed based on the `deploy` flag for that artifact in the manifest.
3	This specifies the format for referencing artifact IDs from the manifest.

Deployer workflow structure

A deployer workflow must accept manifest and environment as workflow_call inputs and use conditional if logic to control per-component deployment. The following is the structure of an auto-generated deployer for three components:

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: deployer
on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true
      manifest:
        type: string
        required: true
jobs:
  MyAppAPIs:
    if: ${{ fromJSON(inputs.manifest)['MyAppAPIs']['MyAppAPIs'].deploy }}
    uses: gmaxey/MyAppAPIs/.cloudbees/workflows/deploy.yaml
    with:
      artifact-id: ${{ fromJSON(inputs.manifest)['MyAppAPIs']['MyAppAPIs'].id }}
      environment: ${{ inputs.environment }}
  MyAppFE:
    if: ${{ fromJSON(inputs.manifest)['MyAppFE']['MyAppFE'].deploy }}
    uses: gmaxey/MyAppFE/.cloudbees/workflows/deploy.yaml
    with:
      artifact-id: ${{ fromJSON(inputs.manifest)['MyAppFE']['MyAppFE'].id }}
      environment: ${{ inputs.environment }}
  MyAppBE:
    if: ${{ fromJSON(inputs.manifest)['MyAppBE']['MyAppBE'].deploy }}
    uses: gmaxey/MyAppBE/.cloudbees/workflows/deploy.yaml
    with:
      artifact-id: ${{ fromJSON(inputs.manifest)['MyAppBE']['MyAppBE'].id }}
      environment: ${{ inputs.environment }}▼

The assisted deployer creation uses the components currently associated with your application and creates a job for each component that calls its deploy.yaml file, passes artifact-id and environment values, and adds conditional if logic to only deploy what’s in the manifest.

Release management reference

Release statuses

Release manifest format

Deployer workflow structure

Related pages