Guardrail rules

A guardrail rule is a plain-language instruction that tells the reviewer what to flag. Rules belong to your organization. Architects and Admins manage them under Guardrails. Viewers can read them.

The five starter rules

Every organization starts with these rules, created by npm run db:seed.

Rule Severity Flags
No Cross-Domain Database Coupling Blocking A service importing ORM entities, schemas or connection settings owned by another bounded context.
Breaking API Contract Detection Blocking OpenAPI, GraphQL or Protobuf changes that remove fields, change types or make parameters required without versioning.
Unapproved Cloud / IaC Provisioning Blocking Terraform, CDK or CloudFormation changes that add non-standard services or permissive IAM and network rules.
Destructive Schema Migration Guard Blocking DROP TABLE, DROP COLUMN, or foreign keys without an index in Liquibase, Flyway, Prisma or SQL migrations.
New External Dependency & License Check Warning A newly added library in package.json, pom.xml, build.gradle, go.mod or requirements.txt. Also triggers an ADR draft.

Severity

  • Blocking: makes the build status failed.
  • Warning: appears in the comment, but the status stays successful.

Create or edit a rule

  1. Open Guardrails.
  2. Under New rule, fill in:
    • Name: unique within your organization.
    • Description: a short explanation for readers.
    • Severity.
    • Instruction for the reviewer: at least 10 characters. Say what to flag and, if useful, what is acceptable.
    • Target file patterns: glob patterns, one per line, for example **/*.tf. Leave empty to apply the rule to every changed file.
  3. Select Create rule.

To change a rule, open it with Edit, adjust the fields and select Save. You can also Disable (keeps the rule, stops using it) or Delete it.

Tuning rules

  • Start with severity Warning for new rules. Promote to Blocking once the findings are reliable.
  • Keep each rule to one idea. Short, specific instructions give steadier results than long ones.
  • Use target patterns so a rule only sees relevant files.
  • Remember the triage step: a rule over ordinary source files only runs when the pull request also changes a file matching the repository's structural triggers.

Rule names and results

The reviewer must report a violation using the exact rule name. Renaming a rule affects how its past results are grouped on the dashboard.