> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository Rules

> Create automated workflows using natural language — no code required

export const ThemeImage = ({src, alt}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} />
    </span>;
};

## Overview

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

<CardGroup cols={3}>
  <Card title="Natural Language" icon="message">
    Write rules in plain English, not code
  </Card>

  <Card title="Git-Native" icon="code-branch">
    Rules live in your repo as `.gitar/rules/*.md`
  </Card>

  <Card title="Integrations" icon="plug">
    Connect to Jira, Linear, Slack, and more
  </Card>
</CardGroup>

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

## Quick Start

<Steps>
  <Step title="Create the Rules Directory">
    ```bash theme={null}
    mkdir -p .gitar/rules
    ```
  </Step>

  <Step title="Add a Rule File">
    Create `.gitar/rules/security-review.md`:

    ```markdown theme={null}
    ---
    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
    ```
  </Step>

  <Step title="Commit and Push">
    ```bash theme={null}
    git add .gitar/rules/
    git commit -m "Add security review rule"
    git push
    ```
  </Step>

  <Step title="Open a PR">
    Gitar evaluates your rules on every PR. Check the dashboard comment to see which rules matched.
  </Step>
</Steps>

## Rule Structure

Rules are markdown files with YAML frontmatter:

```markdown theme={null}
---
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

<AccordionGroup>
  <Accordion title="Post Comments">
    Post comments on the PR or as inline code reviews.

    ```markdown theme={null}
    actions: "Post a comment summarizing the database schema changes"
    ```
  </Accordion>

  <Accordion title="Apply Labels">
    Add or remove labels based on detected conditions.

    ```markdown theme={null}
    actions: "Add 'needs-docs' label if README is modified"
    ```
  </Accordion>

  <Accordion title="Assign Reviewers">
    Assign specific reviewers when changes are detected.

    ```markdown theme={null}
    actions: "Assign @backend-team for API changes"
    ```
  </Accordion>

  <Accordion title="Suggest Code Changes">
    Suggest or make code modifications.

    ```markdown theme={null}
    actions: "Suggest adding error handling for new API endpoints"
    ```
  </Accordion>
</AccordionGroup>

## Integrations

### Jira

Link PRs to Jira tickets and update issue status automatically.

```markdown theme={null}
---
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](/integrations/jira) for setup instructions.

### Linear

Link PRs to Linear issues and update their status automatically.

```markdown theme={null}
---
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](/integrations/linear) for setup instructions.

### Slack

Send notifications to Slack channels.

```markdown theme={null}
---
title: "Notify on Deploy"
when: "PR is merged to main"
actions: "Post deployment notification to #releases"
integrations: ["slack"]
---
```

See [Slack Integration](/integrations/slack) 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.

```markdown theme={null}
---
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](/integrations/custom-integrations) for setup instructions.

## Example Rules

### Documentation Required

```markdown theme={null}
---
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

```markdown theme={null}
---
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

```markdown theme={null}
---
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)                              |

<ThemeImage src="/assets/images/display-verbose-light.png" alt="Verbose display mode showing all rules" />

## Best Practices

<CardGroup cols={2}>
  <Card title="Be Specific" icon="bullseye">
    Narrow conditions prevent false positives. "PRs modifying `src/auth/*.ts`" is better than "PRs with auth changes".
  </Card>

  <Card title="Keep Rules Focused" icon="scissors">
    One rule, one purpose. Split complex logic into multiple rules.
  </Card>

  <Card title="Test with Verbose Mode" icon="bug">
    Use `gitar display:verbose` to debug why rules aren't matching.
  </Card>

  <Card title="Document Edge Cases" icon="book">
    Include examples and edge cases in the rule body.
  </Card>
</CardGroup>