Umbraco.Deploy.Automate 18.0.4

<p align="center"> <img alt="Umbraco Automate" src="./assets/logo-128.png" width="128"> </p>

Umbraco.Deploy.Automate

The integration package between Umbraco Deploy and Umbraco Automate.

This package does three things:

1. Transfers Automate entities through Deploy — workspaces, workspace groups, automations, and connections move between environments using the same Queue / Restore / Partial Restore flows you already use for content and schema.
2. Exposes Deploy events as Automate triggers — build automation flows that react to deployment activity (task completed/failed, artifact exported/imported, files written/deleted, and more).
3. Exposes Deploy operations as Automate actions — call Deploy from an automation step to deploy content, queue items for transfer, or trigger a restore.

Installation

dotnet add package Umbraco.Deploy.Automate

DeployAutomateComposer is auto-discovered by Umbraco's composition system; no manual registration is required.

Requirements

Part 1 — Deploying Automate entities

The package registers Deploy service connectors for the four user-defined Automate entities, so each one appears in the Deploy back-office tree alongside content and schema. Queue for Transfer, Restore, and Partial Restore all work as expected.

Supported entities

Runtime entities (AutomationRun, StepRun) are intentionally not transferable — execution history is per-environment.

Dependency resolution

Connectors emit Match dependencies so target environments resolve the graph automatically:

• A workspace depends on its allowed Connections and on the UserGroups assigned to it.
• A workspace group depends on its Workspace and (if nested) on its parent group.
• An automation depends on its Workspace, optional WorkspaceGroup, and on every Connection referenced by a step.
• A connection has no Automate-side dependencies.

Process passes are ordered to honour the graph: Connections (pass 2) → Workspaces (pass 3) → Workspace Groups (passes 4 & 5 — second pass reparents) → Automations (pass 6).

Preserved settings

All user-facing settings round-trip with two intentional exceptions:

• Automation.Status and Automation.PublishedVersion are not overwritten on update. Redeploying a live automation does not knock it back to draft; the target environment's lifecycle state is preserved. New automations are created as Draft so an operator must explicitly publish on the target.
• Connection settings are filtered on export and merged (not replaced) on import, applied in this precedence order:
  1. Field names listed in IgnoreSettings are stripped unconditionally.
  2. If IgnoreSensitive is enabled, every field marked [Field(IsSensitive = true)] on the connection type's settings schema is stripped, regardless of its value — including $ configuration references. Off by default.
  3. Values prefixed with ENC: are stripped when IgnoreEncrypted is enabled (default). $-prefixed configuration references are passed through.
  • Settings already present on the target are preserved for any key not in the artifact.
• Sensitive trigger / step settings flagged via the action or trigger's settings schema (IsSensitive = true) are stripped from automation artifacts before serialization. The rest of the step (id, alias, name, connection id, input mappings, position, error behaviour, retries) is preserved verbatim.

Validation on import

Importing fails fast (rather than landing dangling references) when the target site is missing a contributing package:

• An automation referencing an unknown TriggerAlias or step ActionAlias.
• A connection of an unknown Type alias.

The error message names the missing alias and points at the absent package.

Configuration

{
  "Umbraco": {
    "Deploy": {
      "Automate": {
        "Connections": {
          "IgnoreEncrypted": true,
          "IgnoreSensitive": false,
          "IgnoreSettings": [ "apiKey", "clientSecret" ]
        }
      }
    }
  }
}

A JSON schema for these options is shipped at appsettings-schema.Umbraco.Deploy.Automate.json.

Part 2 — Deploy events as Automate triggers

Umbraco Deploy publishes its notifications through the standard Umbraco CMS notification pipeline, so the triggers below subscribe to them natively — no bridge handlers are required.

Must-have triggers

Note on "deployment started": Umbraco Deploy does not publish a dedicated task-started notification. TaskNotification is the base class only; the pipeline publishes TaskCompletedNotification or TaskFailedNotification as the terminal events. Use WorkContextPreparingTrigger (Advanced) as the closest signal to a "deployment starting" event.

TaskCompletedTrigger output

TaskFailedTrigger output

ArtifactExportedTrigger / ArtifactImportedTrigger output

Nice-to-have triggers

FilesWrittenTrigger / FilesDeletedTrigger / UserUpdatedTrigger output

RemoteCompletedTrigger output

DiskTriggeredTrigger output

Advanced triggers

Cancelable notifications: ArtifactExportingTrigger, ArtifactImportingTrigger, and ValidateArtifactImportTrigger are backed by cancelable Deploy notifications. Cancellation is not available through the Automate trigger system — these triggers fire for observation only.

ArtifactExportingTrigger / ArtifactImportingTrigger output

Same properties as the post-export/import triggers (ArtifactUdi, ArtifactType, ArtifactAlias, ArtifactName), but fires before the operation occurs.

ValidateArtifactImportTrigger output

WorkContextPreparingTrigger output

Part 3 — Deploy operations as Automate actions

Run Deploy operations from an Automate flow.

Usage examples

Notify team on deployment failure

Trigger: Task Failed
  → Condition: ExceptionType is not empty
  → Action: Send Slack message to #deployments
            "Deployment failed for {OwnerEmail}: {ExceptionMessage}"

Log every imported document

Trigger: Artifact Imported
  → Condition: ArtifactType == "document"
  → Action: Write to log
            "Imported document '{ArtifactName}' ({ArtifactUdi})"

Monitor deployment duration

Trigger: Task Completed
  → Condition: Duration > 60
  → Action: Log performance warning
            "Long deployment by {OwnerEmail}: {Duration}s, processed {ProcessCount} items"

Repository layout

src/
  Umbraco.Deploy.Automate/
    Actions/                          # Automate actions that call Deploy operations
    Artifacts/                        # Deploy artifacts for Automate entities
    Configuration/                    # DeployAutomateSettings
    Connectors/ServiceConnectors/     # One service connector per Automate entity
    NotificationHandlers/             # Cache refresh handlers for save/delete
    Triggers/                         # Automate triggers backed by Deploy notifications
    Triggers/Outputs/                 # Trigger output types
    Tree/                             # Back-office tree helpers for Deploy dialogs
    Workspaces/                       # WorkspaceGroupDeploySaver (bypasses domain validation)
    DeployAutomateComponent.cs        # Registers UDI, disk, and transfer entity types
    DeployAutomateComposer.cs         # DI composition
tests/
  Umbraco.Deploy.Automate.Tests.Unit/

Future work

The following Deploy operations could be exposed as Automate actions in a future version:

History

This package started life as a small collection of custom Deploy triggers for Umbraco Automate. The Deploy integration for Automate entities originally lived in the Umbraco.Automate monorepo as Umbraco.Automate.Deploy, and was moved into this repo so that the entire Deploy⇄Automate story ships as a single package.

Parts of this package were built with Claude by Anthropic.

License

MIT — see LICENSE for details.