Skip to main content

​
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

​
Quick Start

1

Create the Rules Directory

mkdir -p .gitar/rules
2

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
3

Commit and Push

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

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

FieldRequiredDescription
titleYesRule name displayed in the dashboard
descriptionYesBrief summary shown in compact mode
whenYesNatural language condition that triggers the rule
actionsYesWhat Gitar does when the condition is met
integrationsNoExternal tools the rule needs (jira, linear, slack)

​
Triggers

Rules are evaluated when:
  • A PR/MR is opened — Full rule evaluation on all applicable rules
  • New commits are pushed to a PR/MR — Re-evaluates checks, may fire automations
  • CI fails on a PR/MR — Triggers CI-related automations (e.g. retry unrelated failures)
  • PR/MR metadata updates — Title, description, reviewers, or labels change
  • A PR/MR is closed or merged — Enables post-merge workflows like follow-up issue creation, compliance reporting, and merge-close notifications

​
Supported Actions

Post comments on the PR or as inline code reviews.
actions: "Post a comment summarizing the database schema changes"
Add or remove labels based on detected conditions.
actions: "Add 'needs-docs' label if README is modified"
Assign specific reviewers when changes are detected.
actions: "Assign @backend-team for API 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.

​
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 and merge automatically"
---

# 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:
CommandDescription
gitar display:verboseShow all rules with explanations for why each matched or didn’t
gitar display:compactShow 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.