Create deployer workflows

Create and manage deployer workflows to orchestrate the deployment of all components in an application to a target environment. Deployer workflows are typically called from staged workflows within application releases, 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.

Before creating a deployer workflow, ensure that the application includes at least one component, each component has a ./.cloudbees/workflows/deploy.yaml file, and each deploy.yaml accepts artifact-id (type: string) and environment (type: string) input parameters. The application must also include environment associations.

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 before creating the deployer workflow, the UI walks you through these steps to create the deployer. If a deployer already exists, the UI option to create one no longer appears.

To create a deployer workflow:

Select Applications and select your application.
Select Applications Workflows.
Select Create workflow, and then select Create deployer workflow.

The following 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, and adds conditional if logic to only deploy what’s in the manifest.

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

Edit a deployer workflow 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 a deployer workflow

To save your workflow changes:

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

How deployer workflows work with staged workflows

A deployer is 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, and passes the manifest and the environment for that stage.

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

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 }}▼

Delete a deployer workflow

To delete a deployer workflow:

Open the workflow from the Workflows list.
Select , and then select Delete.

Deleting a deployer that is referenced by staged workflows causes those workflows to fail. Update or remove any dependencies before deleting.