Buzz Workflow Action Types: A Complete Guide to Automation Steps

Buzz provides seven distinct workflow action types—SendMessage, SendDm, SetChannelTopic, AddReaction, CallWebhook, RequestApproval, and Delay—that enable automated messaging, channel management, external integrations, and human-in-the-loop approvals within the block/buzz repository.

The block/buzz repository implements a powerful workflow engine in the buzz-workflow crate, where automation logic is defined through an ordered sequence of steps. Each step contains an action type specified by the ActionDef enum, which determines exactly what operation the executor performs when the workflow runs. Understanding these action types is essential for building effective automations that respond to triggers ranging from message reactions to scheduled cron jobs.

Understanding the ActionDef Enum

The core definition of all workflow action types resides in crates/buzz-workflow/src/schema.rs, specifically within the ActionDef enum. This enum uses internally tagged serialization with #[serde(flatten)] to allow each workflow step to specify exactly one action type alongside its configuration parameters.

When the workflow engine parses a YAML definition, it flattens the action-specific fields directly into the step object. This design means a step's configuration contains both universal metadata (like id) and action-specific fields (like text or url) at the same object level, making the configuration intuitive while maintaining strict type safety in the Rust implementation.

Available Workflow Action Types in Buzz

The ActionDef enum in crates/buzz-workflow/src/schema.rs currently supports seven distinct action types, each designed for specific automation scenarios.

SendMessage

The SendMessage action posts a message to a channel, supporting both new conversations and threaded replies. This is the most commonly used action type for notifications and automated responses.

Key configuration fields include:

• text – The message body supporting template variables (e.g., {{trigger.author}})
• channel – Optional UUID specifying a target channel different from the workflow's default
• reply_in_thread – Boolean flag that, when true, forces the bot to reply to the triggering message rather than starting a new thread

According to the validation logic in WorkflowDef::validate, this action type cannot use reply_in_thread: true when the workflow trigger lacks message context, such as schedule-based or generic webhook triggers.

SendDm

The SendDm action delivers direct messages to specific users, enabling private notifications that avoid channel noise. This action type requires:

• to – The recipient's public key or a template expression like {{trigger.author}}
• text – The private message content

This action is particularly useful for sending sensitive alerts or personal task assignments that should not appear in public channels.

SetChannelTopic

The SetChannelTopic action updates the topic line of the workflow's associated channel. It accepts a single required field:

• topic – The new topic string to display

This action type helps teams automate channel context updates, such as rotating on-call engineer names or displaying current sprint information.

AddReaction

The AddReaction action adds emoji reactions to messages programmatically, providing lightweight acknowledgment mechanisms. The configuration requires:

• emoji – The emoji name (e.g., "thumbsup" or "white_check_mark")

This action only functions correctly when triggered by message-oriented events that provide a target message ID for the reaction attachment.

CallWebhook

The CallWebhook action enables external integrations by executing HTTP requests to third-party endpoints. This action type supports sophisticated API interactions with the following fields:

• url – The target HTTPS endpoint (required)
• method – Optional HTTP verb (defaults to POST)
• headers – Optional map of additional HTTP headers
• body – Optional request payload supporting template variable interpolation

Security validation in WorkflowDef::validate restricts this action type to workflows owned by users with elevated channel authority, preventing unauthorized external data exfiltration.

RequestApproval

The RequestApproval action implements human-in-the-loop workflows by pausing execution until explicit authorization is granted. This action creates approval gates with these parameters:

• from – User mention or role identifier (e.g., "@release-manager")
• message – Descriptive text presented to the approver
• timeout – Optional duration string (defaults to "24h")

If the approval is denied or the timeout expires, the workflow execution stops, making this action critical for deployment pipelines and sensitive operations requiring oversight.

Delay

The Delay action inserts timed pauses between workflow steps, useful for rate limiting or waiting for external processes to complete. It requires:

• duration – Human-readable time period (e.g., "5m", "1h", "30s")

The executor parses these duration strings and suspends workflow processing for the specified interval before resuming with the next step.

How Actions Are Defined in YAML

Buzz workflows use flattened serialization to keep configuration files readable. Each step includes an action field that acts as the discriminant for the ActionDef enum, with the remaining fields depending on the selected action type.

- id: notify
  action: send_message
  text: "Build succeeded"
  channel: "general"
  reply_in_thread: true

This structure maps directly to the Rust enum definition in crates/buzz-workflow/src/schema.rs, where #[serde(flatten)] combines the action tag with its specific payload fields into a cohesive step definition.

Workflow Validation and Security Constraints

Before persisting workflow definitions, the system performs rigorous validation through WorkflowDef::validate. This validation enforces critical constraints on how workflow action types can be used:

• Context Validation: Actions like SendMessage with reply_in_thread: true are rejected if the trigger type (such as schedule or generic webhook) does not provide a message context object.
• Permission Verification: The CallWebhook action requires the workflow owner to possess elevated channel authority, ensuring only trusted users can configure external HTTP requests.
• Enum Integrity: All action tags must correspond to valid ActionDef variants defined in the schema.

These safety checks prevent runtime failures and security vulnerabilities by catching configuration errors during the save operation rather than during execution.

Summary

• The ActionDef enum in crates/buzz-workflow/src/schema.rs defines seven workflow action types: SendMessage, SendDm, SetChannelTopic, AddReaction, CallWebhook, RequestApproval, and Delay.
• Each action type serves specific automation needs, from public channel messaging to private approvals and external HTTP integrations.
• Workflow definitions use flattened YAML syntax where the action field selects the enum variant and remaining fields configure the specific behavior.
• The validation system enforces security constraints, such as requiring elevated permissions for webhooks and verifying message context for thread replies.
• Type definitions are mirrored in TypeScript at desktop/src/shared/api/workflowTypes.ts to maintain consistency between the Rust backend and desktop client interface.

Frequently Asked Questions

How do I configure the SendMessage action type to reply in a thread?

Set the reply_in_thread field to true in your workflow step configuration. Note that this only works when the workflow trigger provides message context, such as a reaction trigger or message trigger. If you attempt to use this with a cron schedule trigger or generic webhook, the WorkflowDef::validate method will reject the configuration because no parent message exists to thread under.

What permissions are required to use the CallWebhook action in Buzz workflows?

The CallWebhook action type requires the workflow owner to have elevated channel authority, as enforced by the validation logic in crates/buzz-workflow/src/schema.rs. This security measure prevents standard users from configuring workflows that could transmit channel data to external URLs. Only users with appropriate administrative privileges can save workflows containing webhook actions.

Can I combine multiple workflow action types in a single Buzz workflow?

Yes, Buzz workflows support sequential combinations of different action types within the steps array. For example, you can chain an AddReaction action to acknowledge a trigger, followed by a Delay action for rate limiting, and conclude with a SendMessage action containing the final results. The executor processes each step in order, with actions like RequestApproval pausing execution until the human approval condition is met.

Where is the workflow action execution logic implemented in the block/buzz codebase?

While the action definitions and schema validation reside in crates/buzz-workflow/src/schema.rs, the actual execution logic for these workflow action types is implemented in crates/buzz-workflow/src/executor.rs. This executor file handles the runtime behavior of each action, such as making HTTP requests for CallWebhook or invoking the messaging APIs for SendMessage. The relay API endpoint at crates/buzz-relay/src/api/workflows.rs handles the CRUD operations for workflow definitions, while the desktop interface uses components in desktop/src/features/workflows/ui/workflowFormPrimitives.tsx to render action type selectors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}