Watchflow: Custom rule checks for GitHub workflows - Agentic GitHub Guardrails

Replace static GitHub protection rules with agentic guardrails. Watchflow is an open-source GitHub App that provides context-aware enforcement, going beyond binary branch protection to prevent production incidents with intelligent, explainable pre-merge checks.

tl;dr

Watchflow is an open-source GitHub App that brings context-aware governance to pull requests, check runs, and deployments. Replace static protection rules with intent-driven rules in the rules.yaml file and enforce behavior across workflows with an agentic engine that interprets GitHub events in real-time.

• → View it on GitHub: github.com/warestack/watchflow 
• → Try out rule evaluation live: watchflow.dev 

Introduction: Beyond Static Rules

Traditional GitHub branch protection rules are binary—they either block or allow. They stop at the merge button and don’t understand context, team dynamics, or the nuanced conditions that matter in real-world development workflows.

What if your protection rules could:

• Understand when a senior developer is making a routine security update vs. a junior developer modifying critical infrastructure?
• Consider deployment timing, team availability, and related incidents?
• Provide explainable decisions that your team can trust?
• Adapt to your team’s actual processes, not just repository-level configurations?

That’s what agentic GitHub guardrails enable—and that’s what Watchflow delivers.

What is Watchflow?

Watchflow is an open-source GitHub App that replaces static protection rules with agentic GitHub guardrails. It ensures consistent quality standards with smarter, context-aware protection for every repository.

Unlike traditional branch protection that ends at the merge button, Watchflow provides:

• Context-aware rule enforcement that considers developer role, timing, and team context
• Human-language rule definitions that your team can read and understand
• Explainable decisions with evidence recorded on PRs and issues
• Intelligent acknowledgment workflows that allow for legitimate exceptions
• Real-time governance that scales with repository activity

How It Started

Watchflow was born from the need to solve real problems that static GitHub protection rules couldn’t address:

Key Requirements

1. Human-readable rules - No proprietary language or complex YAML configurations
2. Explainable decisions - Every rule violation comes with clear reasoning
3. Typed input - Strong typing for rule parameters and conditions
4. Deployment behavior - Rules that understand the full deployment lifecycle
5. Context awareness - Rules that adapt to team structure and developer roles

How Does It Work?

Watchflow uses a hybrid architecture that combines rule-based logic with AI-powered intelligence:

Architecture Overview

GitHub Events → Watchflow → Rule Engine → GitHub Checks
                      ↓
        Security | Compliance | Safety | Custom Checks

Watchflow processes GitHub events (PRs, deployments, comments) and enriches them with:

• PR metadata and diff analysis
• Team information and developer roles
• Deployment history and patterns
• Related incidents and context

The Rule Engine evaluates rules against this enriched data, making context-aware decisions that go beyond simple yes/no checks.

Agentic GitHub Guardrails

The term “agentic” refers to Watchflow’s ability to:

• Reason about context, not just check conditions
• Adapt to team dynamics and real-world scenarios
• Explain decisions with clear, human-readable evidence
• Learn from patterns and team behavior

This is fundamentally different from static branch protection rules that can only answer “yes” or “no” without understanding why.

What You Can Enforce

Watchflow enables four main categories of policies:

1. Security Checks

• Prevent sensitive files from being modified without proper review
• Block merges that introduce security vulnerabilities
• Require security team approval for infrastructure changes

2. Compliance Checks

• Enforce code review requirements based on team structure
• Ensure proper documentation for compliance-critical changes
• Track and audit policy violations

3. Safety Checks

• Prevent deployments during maintenance windows
• Block merges that could cause production incidents
• Require additional approvals for high-risk changes

4. Custom Checks

• Enforce team-specific workflows and processes
• Implement business logic that matters to your organization
• Create rules that map to your actual development practices

Enrichments

Watchflow enriches GitHub events with additional context:

• PR Metadata: File changes, commit history, review status
• Team Info: Developer roles, team assignments, code ownership
• Deployment Behavior: Deployment patterns, timing, success rates
• Related Context: Linked issues, Slack discussions, incident history

This enriched data enables rules to make intelligent decisions that static protection rules simply cannot.

Severity Levels and Enforcement

Watchflow supports multiple enforcement actions:

• Block: Prevent merges or deployments (critical violations)
• Warn: Flag issues without blocking (informational)
• Highlight: Draw attention to potential concerns (advisory)
• Critical: Immediate action required (security/compliance)

Each rule can specify its severity level, allowing teams to balance enforcement with workflow flexibility.

Real Usage and Known Constraints

Common Use Cases

1. Require Top Reviewer Approval: PRs must have approval from one of the top 5 most active reviewers
2. Conventional Commits: Enforce commit message format (feat/fix/etc.)
3. Code Owner Approval: Prevent direct merges to main without code owner review
4. Weekend Deployment Protection: Block deployments on weekends unless acknowledged

Known Constraints

• Rules are evaluated at PR creation and update events
• Some GitHub API rate limits may apply for high-activity repositories
• Complex rules may require additional processing time

Natural Language Rules

One of Watchflow’s key features is the ability to define rules in natural language:

rules:
  - description: All pull requests must have a minimum number of approvals unless the author is a maintainer
    enabled: true
    severity: high
    event_types: [pull_request]
    parameters:
      min_approvals: 2

This human-readable format makes rules:

• Understandable by non-technical team members
• Maintainable without deep technical knowledge
• Explainable when violations occur

Call for Contributors and Feedback

Watchflow is open source and made with ❤️ by Warestack and the community. We welcome contributions!

Get Involved

• GitHub Repository: github.com/warestack/watchflow 
• Documentation: watchflow.dev 
• Try the Demo: Experience Watchflow’s agentic guardrails in action
• Join the Discussion: Share feedback and use cases

Watchflow vs. Traditional GitHub Protection Rules

Final Thoughts

Agentic GitHub guardrails represent the next evolution of DevOps governance. Watchflow demonstrates that protection rules don’t have to be rigid, binary, or repository-bound. They can be intelligent, context-aware, and aligned with how teams actually work.

By replacing static protection rules with agentic guardrails, teams can:

• Prevent production incidents with smarter, context-aware checks
• Maintain workflow flexibility while enforcing critical policies
• Build trust through explainable, evidence-based decisions
• Scale governance across teams and repositories

Watchflow is our contribution to the open-source community—a tool that makes agentic GitHub guardrails accessible to every team.

Ready to replace your static protection rules with agentic guardrails? Get started with Watchflow  or explore the code on GitHub .

For enterprise-grade features, advanced integrations, and team management, check out Warestack —the platform that powers Watchflow and extends it with production-scale capabilities.