Repository Rules

Overview

Repository rules let you define automated workflows using plain markdown files. When conditions are met, Gitar automatically executes actions — 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

Repository rules are available on the Pro plan (up to 5 custom rules per organization) and Enterprise plan (unlimited rules).

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.

Rule Structure

Rules are markdown files with YAML frontmatter:

---
title: "Rule Name"
description: "Brief summary of what this rule does"
when: "Condition that triggers the rule"
actions: "What Gitar does when condition is met"
integrations: ["jira", "slack"]  # Optional
---

# Detailed Instructions

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

Frontmatter Fields

Field	Required	Description
`title`	Yes	Rule name displayed in the dashboard
`description`	Yes	Brief summary shown in compact mode
`when`	Yes	Natural language condition that triggers the rule
`actions`	Yes	What Gitar does when the condition is met
`integrations`	No	External tools the rule needs (`jira`, `linear`, `slack`)

Triggers

Rules are evaluated when:

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 — Triggers CI-related automations (e.g. retry unrelated failures)
PR metadata updates — Title, description, reviewers, or labels change
A PR is closed or merged — Enables 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

Jira

Link PRs to Jira tickets and update issue status automatically.

---
title: "Jira Sync"
when: "PR title or branch contains Jira ticket ID"
actions: "Link PR to Jira ticket and update status"
integrations: ["jira"]
---

See Jira Integration for setup instructions.

Linear

Link PRs to Linear issues and update their status automatically.

---
title: "Linear Sync"
when: "PR title or branch contains a Linear issue ID (e.g. ENG-123)"
actions: "Link PR to the Linear issue and move it to In Review"
integrations: ["linear"]
---

See Linear Integration for setup instructions.

Slack

Send notifications to Slack channels.

---
title: "Notify on Deploy"
when: "PR is merged to main"
actions: "Post deployment notification to #releases"
integrations: ["slack"]
---

See Slack Integration for setup instructions.

Custom Integrations (MCP)

On the Enterprise plan you can connect your own MCP servers as custom integrations and reference them from a rule by slug, just like the built-in integrations.

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

See Custom Integrations for setup instructions.

Example Rules

Documentation Required

---
title: "Documentation Required"
description: "Ensure API changes include documentation updates"
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

Auto-merge Dependabot

---
title: "Auto-merge Dependabot"
description: "Auto-merge minor dependency updates from Dependabot"
when: "Dependabot PRs for minor or patch version updates with passing CI"
actions: "Approve the PR and add the auto-merge label"
---

# Auto-merge Criteria

Automatically merge when:
- PR author is dependabot[bot]
- Update is minor or patch version
- All CI checks pass
- No security vulnerabilities introduced

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

Be Specific

Narrow conditions prevent false positives. “PRs modifying src/auth/*.ts” is better than “PRs with auth changes”.

Keep Rules Focused

One rule, one purpose. Split complex logic into multiple rules.

Test with Verbose Mode

Use gitar display:verbose to debug why rules aren’t matching.

Document Edge Cases

Include examples and edge cases in the rule body.

Get Started

Features

Configuration

Resources

Repository Rules

Overview

Natural Language

Git-Native

Integrations

Quick Start

Rule Structure

Frontmatter Fields

Triggers

Supported Actions

Integrations

Jira

Linear

Slack

Custom Integrations (MCP)

Example Rules

Documentation Required

Breaking Change Review

Auto-merge Dependabot

Debugging

Best Practices

Be Specific

Keep Rules Focused

Test with Verbose Mode

Document Edge Cases

​Overview

Natural Language

Git-Native

Integrations

​Quick Start

​Rule Structure

​Frontmatter Fields

​Triggers

​Supported Actions

​Integrations

​Jira

​Linear

​Slack

​Custom Integrations (MCP)

​Example Rules

​Documentation Required

​Breaking Change Review

​Auto-merge Dependabot

​Debugging

​Best Practices

Be Specific

Keep Rules Focused

Test with Verbose Mode

Document Edge Cases

Overview

Quick Start

Rule Structure

Frontmatter Fields

Triggers

Supported Actions

Integrations

Jira

Linear

Slack

Custom Integrations (MCP)

Example Rules

Documentation Required

Breaking Change Review

Auto-merge Dependabot

Debugging

Best Practices