Repository Rules

Overview

Repository rules let you define automated workflows using plain markdown files. When conditions are met, Gitar automatically executes actions, with no code required.

Natural Language

Write rules in plain English, not code

Git-Native

Rules live in your repo as .gitar/rules/*.md

Integrations

Connect to Jira, Linear, Slack, and more

Quick Start

Create the Rules Directory

mkdir -p .gitar/rules

Add a Rule File

Create .gitar/rules/security-review.md:

---
title: "Security Review"
description: "Require security team review for sensitive changes"
when: "PRs modifying authentication or encryption code"
actions: "Assign security team and add label"
---

# Security Review

When sensitive code is modified:
- Assign @security-team as reviewer
- Add "security-review" label
- Post comment with security checklist

Commit and Push

git add .gitar/rules/
git commit -m "Add security review rule"
git push

Open a PR

Gitar evaluates your rules on every PR. Check the dashboard comment to see which rules matched. When none of them apply, the comment says how many were skipped, and gitar display:verbose shows why each was skipped.

Rule Structure

Rules are markdown files with YAML frontmatter:

---
title: "Rule Name"
description: "Brief summary of what this rule does"
type: check
when: "Condition that triggers the rule"
actions: "What Gitar does when condition is met"
---

# Detailed Instructions

Natural language description of the rule behavior.
Include specific examples, edge cases, or additional context.

Frontmatter Fields

Field	Purpose
`title`	Names the rule in the dashboard. Without one, Gitar uses the heading or filename.
`description`	Summarizes the rule.
`slug`	Optional custom rule identifier. It does not preserve evaluation history when the file is renamed.
`when`	States the condition that triggers the rule.
`actions`	Describes what Gitar does when the condition matches.
`type`	`check` validates a requirement. `automation` takes an action. Without a type, Gitar infers it from the rule.

Triggers

Event	What Gitar evaluates
A PR is opened	Full rule evaluation on all applicable rules
New commits are pushed to a PR	Re-evaluates checks, may fire automations
CI fails on a PR	CI-related automations, such as retrying unrelated failures
PR metadata updates	Title, description, reviewers, or labels change
A PR is closed or merged	Post-merge workflows like follow-up issue creation, compliance reporting, and merge-close notifications

Supported Actions

Post Comments

Post comments on the PR or as inline code reviews.

actions: "Post a comment summarizing the database schema changes"

Apply Labels

Add or remove labels based on detected conditions.

actions: "Add 'needs-docs' label if README is modified"

Assign Reviewers

Assign specific reviewers when changes are detected.

actions: "Assign @backend-team for API changes"

Suggest Code Changes

Suggest or make code modifications.

actions: "Suggest adding error handling for new API endpoints"

Integrations

Every integration your organization has enabled is available to every rule. Name one in the rule and the agent uses it, so post to #releases finds Slack and move the ticket to In Review finds Linear.

Integration	Example action	Setup
Jira	Link the PR to a ticket and update its status.	Jira
Linear	Move a linked issue to In Review.	Linear
Slack	Post a merge notification to a channel.	Slack

Custom Integrations (MCP)

On the Enterprise plan you can connect your own MCP servers as custom integrations. Name one in a rule the same way you name a built-in.

---
title: "Internal Docs Enrichment"
when: "PRs that modify a documented internal service"
actions: "Comment with links to the relevant internal docs"
---

When a PR touches a documented service, use the Acme Search integration to
find the relevant internal docs and link them in a review comment.

See Custom Integrations for setup instructions.

Skills

A rule can also call a skill, a procedure committed under .gitar/skills/<name>/SKILL.md. Name it in the rule body and the agent loads it and follows it.

---
title: "Migration Safety"
when: "PRs that add or modify files under db/migrations/"
actions: "Comment with any reversibility or ordering problems"
---

When a PR touches `db/migrations/`, use the `migration-check` skill and post
its findings as a review comment.

Naming the skill is what invokes it. Gitar has no slash-command syntax. See Skills for the file format. To call the same skill from rules in every repository, commit it once to your configuration repository.

Rules for Every Repository

A rule in .gitar/rules/ applies to the repository that holds it. To apply one across the organization, commit it to your configuration repository instead and every repository evaluates it. A repository overrides an inherited rule with a file of the same name, ignoring case and treating - and _ alike. Commit .gitar/rules/no-raw-sql.md and the configuration repository’s no-raw-sql.md (or no_raw_sql.md) is skipped for that repository.

Example Rules

Each example below is one complete .gitar/rules/*.md file.

Documentation Required

---
title: "Documentation Required"
description: "Require documentation updates alongside API changes"
when: "PRs adding or modifying API endpoints"
actions: "Request documentation update if not included"
---

# Documentation Requirements

When API endpoints are added or modified:
1. Check if corresponding docs are updated
2. If not, add "needs-docs" label
3. Post comment requesting documentation

Breaking Change Review

---
title: "Breaking Change Review"
description: "Flag PRs with breaking changes for extra review"
when: "PRs with breaking changes to public APIs"
actions: "Add breaking-change label and request senior review"
---

# Breaking Change Detection

Detect breaking changes:
- Removed public methods or fields
- Changed method signatures
- Modified API response schemas

When detected:
- Add "breaking-change" label
- Assign @api-owners as reviewers
- Post checklist for migration guide

For dependency updates that should merge automatically, configure Auto-Approve and Auto-Merge criteria.

Debugging

Use display mode commands to see how rules are being evaluated:

Command	Description
`gitar display:verbose`	Show all rules with explanations for why each matched or didn’t
`gitar display:compact`	Show only relevant rules (default)

Best Practices

Keep each rule focused on one outcome. Name specific paths and conditions, and include the exceptions that matter to the team. Use gitar display:verbose to check why a rule matched or was skipped.

Get Started

Features

Configuration

Resources

Repository Rules

Overview

Natural Language

Git-Native

Integrations

Quick Start

Rule Structure

Frontmatter Fields

Triggers

Supported Actions

Integrations

Custom Integrations (MCP)

Skills

Rules for Every Repository

Example Rules

Documentation Required

Breaking Change Review

Debugging

Best Practices

​Overview

Natural Language

Git-Native

Integrations

​Quick Start

​Rule Structure

​Frontmatter Fields

​Triggers

​Supported Actions

​Integrations

​Custom Integrations (MCP)

​Skills

​Rules for Every Repository

​Example Rules

​Documentation Required

​Breaking Change Review

​Debugging

​Best Practices

Overview

Quick Start

Rule Structure

Frontmatter Fields

Triggers

Supported Actions

Integrations

Custom Integrations (MCP)

Skills

Rules for Every Repository

Example Rules

Documentation Required

Breaking Change Review

Debugging

Best Practices