Deployer workflows

A deployer workflow is a reusable workflow that orchestrates deployment of all components in an application to a target environment. Deployer workflows are typically used within application releases through staged workflows, enabling consistent and automated multi-component deployments.

Deployer workflows:

Accept a manifest input: a JSON string with artifact version details for each component.
Accept an environment input: the name of the environment to deploy to.
Call each component’s deploy.yaml workflow using the inputs provided.
Deploy only the components listed in the manifest using conditional if logic.

Prerequisites

Before creating a deployer workflow, ensure:

The application includes at least one component.
Each component has a ./.cloudbees/workflows/deploy.yaml file.
Each deploy.yaml accepts the following input parameters:
- artifact-id: Artifact version to be deployed (type: string)
- environment: Target environment name (type: string)
The application includes environment associations (Environments).

If these conditions are not met, the generated deployer workflow may need manual editing.

Create a deployer workflow

The deployer workflow can be created on demand through the UI. If you attempt to create a staged workflow prior to creating the deployer workflow, the UI walks you through these steps to create the deployer. If there is a deployer, the UI option to create one no longer appears.

To create a deployer workflow in the CloudBees platform:

Go to Applications and select Application.
Select Applications Workflows.
Select Create workflow, and then select Create deployer workflow.

This is an example of a deployer workflow auto-generated 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.
Adds conditional if logic to only deploy what’s in the manifest.

The workflow can be committed and used immediately, or customized further.

Edit your deployer using the Workflow Composer

To view and update the deployer workflow visually:

From the Workflows tab, select the deployer workflow.
Select to open the Workflow Composer.
Use the workflow composer to add trigger inputs, jobs, or approvals.

All edits are reflected in the underlying YAML.

Save the workflow

To save your workflow changes:

Select Commit.
Enter a Commit message.
Select Commit again to confirm.

How deployers work with staged workflows

A deployer is often called from staged workflows in release pipelines.

Each stage in a staged workflow:

Corresponds to an environment (for example, staging or production).
Calls the deployer workflow using: ./.cloudbees/workflows/deployer.yaml
Passes the manifest and the environment for that stage.

Example: staged workflow calling deployer.yaml

jobs:
  pre-prod:
    environment: pre-prod
    uses: ./.cloudbees/workflows/deployer.yaml
    with:
      manifest: ${{ inputs.manifest }}
      environment: ${{ job.environment }}
  prod:
    environment: prod
    uses: ./.cloudbees/workflows/deployer.yaml
    with:
      manifest: ${{ inputs.manifest }}
      environment: ${{ job.environment }}▼

This allows a single deployer to serve multiple environments with consistent logic.

Delete a deployer workflow

To delete a deployer:

Open the workflow from the Workflows list.
Use the context menu to select Delete.

Deleting a deployer that’s referenced by staged workflows will cause those workflows to fail. Update or remove any dependencies before performing this action.

References

Refer to these related topics: