Herald: Phabricator’s Custom Notification and Automation Engine

Greg Foster
Greg Foster
Graphite software engineer

Herald is a powerful automation tool within Phabricator that enables users to create custom rules to automate workflows and notifications. This detailed sub-page explores Herald’s capabilities, how to leverage it for productivity, and best practices for setting up effective automation.


Herald stands out as a flexible rule-based engine that triggers actions based on events within Phabricator, such as code commits, task updates, or differential revisions. It is designed to streamline processes and keep relevant parties informed without manual intervention.

  • Custom Rules: Create rules that trigger actions automatically when certain conditions are met.

  • Support for Various Objects: Herald can create rules for different Phabricator objects, including Differential Revisions, Diffusion Commits, Maniphest Tasks, and more.

  • Flexible Conditions: Rules can be based on a wide range of conditions, such as the content of a commit message or the status of a task.

  • Notification and Actions: Herald can send notifications, add subscribers to tasks, enforce policies, and more.

  • Personal and Global Rules: Users can set up personal rules for their actions or administrators can set global rules for the entire instance.

  • Global Rules: Created by administrators and apply to all objects in Phabricator.

  • Object Rules: Specific to an object type, such as commits or tasks.

  • Personal Rules: Apply only to actions taken by the individual user.

  • Conditions: Set up specific criteria for when a rule should trigger, using a variety of fields and conditions.

  • Actions: Determine what happens when a rule is triggered, from sending an email to modifying an object.

  • Notify Reviewers: Automatically notify potential reviewers when a new differential revision is created.

  • Task Updates: Inform project members when tasks are updated or closed.

  • Commit Protocols: Ensure commit messages follow a specific format or contain certain keywords.

  • Security Policies: Enforce security policies by restricting actions based on user roles or other criteria.

Herald integrates with the broader Phabricator ecosystem:

  • Differential: Trigger actions based on code review activities.

  • Maniphest: Create rules for task creation, updates, and prioritization.

  • Diffusion: Apply rules to code pushes and repository events.

Effective use of Herald involves strategic rule creation:

  • Clear Objectives: Understand what you aim to achieve with each rule to avoid unnecessary complexity.

  • Minimalist Approach: Start with simple rules and add complexity as needed to avoid unintended consequences.

  • Regular Audits: Review and refine rules periodically to ensure they remain relevant and efficient.

For advanced use cases, Herald provides additional capabilities:

  • Webhooks: Trigger webhooks to integrate with external systems and extend automation beyond Phabricator.

  • Rule Templates: Use templates to quickly create rules for common scenarios.

Herald serves as a cornerstone of automation within Phabricator, enabling teams to create a tailored, self-operating workflow that maximizes efficiency and consistency. By understanding and utilizing Herald's robust rule system, teams can significantly reduce manual overhead, ensuring that their focus remains on the core objectives of development and project management.

The subsequent pages will detail how Herald’s automation can be finely tuned to work with Phabricator’s array of tools, facilitating a seamless and automated development environment.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2