Herald is an automation tool within Phabricator that enables users to create custom rules to automate workflows and notifications. This detailed guide 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.
However, it is important to note that Herald is no longer actively maintained following the deprecation of Phabricator as a whole. For teams seeking a modern, supported alternative, Graphite offers robust features tailored specifically for automated code review and developer workflows, which we will discuss later in the guide.
Features of Herald
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.
Creating and managing rules
Types of rules
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.
Rule conditions and actions
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.
Use cases for Herald
Automated notifications
Notify reviewers: Automatically notify potential reviewers when a new differential revision is created.
Task updates: Inform project members when tasks are updated or closed.
Workflow enforcement
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.
Integration with other Phabricator applications
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.
Best practices in rule creation
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.
Advanced features
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.
Graphite Automations and platform overview
Graphite is a modern developer platform designed to simplify complex coding workflows, enhance collaboration, and improve productivity through streamlined code reviews and project management. With advanced automation capabilities, Graphite helps teams efficiently handle pull requests (PRs), enabling faster reviews and merges, while maintaining clarity and reducing manual overhead. Actively maintained and optimized for contemporary development practices, Graphite emphasizes ease of use, flexibility, and seamless integration within existing workflows.
Features of Graphite Automations
- Rule-based automations: Graphite enables the creation of sophisticated automation rules triggered by pull request attributes.
- Filter triggers: Automations can activate based on specific conditions, such as the PR author, file changes in specific directories, file suffixes, and various other criteria.
- Multiple actions: Once triggered, automations can execute actions including assigning reviewers, labeling PRs, adding assignees, commenting, sending Slack notifications, or even posting GIFs from GIPHY to celebrate fully approved PRs.
- Glob patterns: Supports creating detailed rules based on glob patterns, enabling targeted automation for specific file types or directories.
Creating and managing automations
Creating rules
- Navigate to Automations from Graphite's web app.
- Select "Create rule" and specify conditions for triggering actions based on repository-specific criteria.
- Preview matched historical PRs to verify rule accuracy.
- Activate the rule to apply immediately to existing and future PRs meeting specified conditions.
Viewing and editing rules
- Graphite provides an intuitive interface to view all active automation rules within accessible repositories.
- Easily edit existing rules by navigating to the Automations interface and selecting the edit icon.
- Changes to rules will apply only to new matches; previously matched PRs will not re-trigger.
Use cases for Graphite automations
Reviewer assignment
- Automatically assign appropriate reviewers or teams based on the PR author or modified directories.
Labeling and organization
- Apply descriptive labels automatically to facilitate efficient PR management and sorting within the Graphite PR inbox.
PR comments and notifications
- Leave informative comments automatically for PRs impacting sensitive or critical code areas.
- Set up Slack notifications to stay informed about key changes without direct reviewer involvement.
The Graphite platform
The broader Graphite ecosystem includes:
- PR inbox: Centralized management of PRs with efficient filtering and navigation.
- CLI tool and VS Code extension: Enhanced Git workflows enabling efficient handling of stacked pull requests, reducing manual overhead.
- Stacked PR workflow: Simplify complex PR processes, leading to clearer reviews and faster merges.
- AI powered code reviews: Graphite's AI-powered code review tool, Diamond, provides intelligent suggestions and insights, streamlining the review process and enhancing code quality.
Conclusion
Herald serves as a cornerstone of automation within Phabricator, enabling teams to create a tailored, self-operating workflow that maximizes efficiency and consistency. But the Graphite platform represents a modern, powerful alternative to Herald and Phabricator. By leveraging Graphite's intuitive automation features, development teams can significantly streamline workflows, reduce overhead, and maintain a more efficient, manageable code review process.