> ## 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 Configuration

> Configure Gitar's behavior at the repository level with instruction files, review rules, and the .gitar directory

## Overview

Gitar reads configuration from your repository to customize its behavior. This includes AI instruction files, custom review rules, and repository-level automation rules. All configuration lives in your codebase and is version-controlled alongside your code.

## AI Instruction Files

Gitar recognizes the following files as AI instruction sources. Place these at the root of your repository:

| File              | Description                                       |
| ----------------- | ------------------------------------------------- |
| `AGENTS.md`       | General AI agent instructions for your repository |
| `CLAUDE.md`       | Claude-specific instructions and conventions      |
| `.cursorrules`    | Cursor-compatible instruction file                |
| `.cursor/rules/*` | Directory of Cursor rule files                    |

When Gitar processes a PR, it reads these files to understand your repository's conventions, coding standards, and best practices. This context is used during both code review and CI failure fixing.

<Note>
  These files are read automatically -- no additional configuration is needed. Simply commit them to your repository root and Gitar will pick them up.
</Note>

## The .gitar Directory

The `.gitar` directory is the primary location for Gitar-specific configuration:

```
your-repo/
  .gitar/
    rules/        # Repository rules (automation workflows)
      *.md
    review/       # Custom code review instructions
      *.md
    documents/    # Supporting documents for review includes
      *.md
```

| Directory           | Purpose                                                                        |
| ------------------- | ------------------------------------------------------------------------------ |
| `.gitar/rules/`     | Natural-language automation rules that trigger actions when conditions are met |
| `.gitar/review/`    | Custom instructions that tailor what Gitar looks for during code review        |
| `.gitar/documents/` | Supporting files that can be referenced from review instructions               |

## Custom Review Instructions

The `.gitar/review/` directory lets you tailor Gitar's code review to your project's specific requirements. Add one or more markdown files containing instructions, checks, or gotchas that Gitar should consider during reviews.

Multiple files can be used to organize instructions by topic -- for example, separate files for security rules, performance guidelines, and project-specific gotchas.

**Example:** A file named `.gitar/review/gotchas.md` that documents codebase-specific patterns:

```markdown theme={null}
# Logging Gotchas

- Use `info!` for logging that requires operational visibility
- Leave `debug!` for local debugging only
- Our telemetry only renders logs with severity `info` or higher
```

### Including Specific Files

You can include content from other files using the `@` syntax with a relative path. Paths are first resolved relative to the source file, with a fallback to the repository root if not found.

**Example:** Given the following directory structure:

```
your-repo/
  .gitar/
    review/
      gotchas.md
    documents/
      rust_best_practices.md
  shared/
    common_rules.md
```

From `.gitar/review/gotchas.md`, you can include files using either approach:

```markdown theme={null}
# Gotchas for Rust Code

@../documents/rust_best_practices.md

@shared/common_rules.md

# Other project-specific gotchas
...
```

* `@../documents/rust_best_practices.md` -- uses `../` to navigate up from `review/` to `.gitar/`, then into `documents/`
* `@shared/common_rules.md` -- not found relative to `review/`, so falls back to repo root resolution

This works recursively -- an included file can itself include other files.

## Repository Rules

Repository rules let you create automated workflows using natural language, specified in `.gitar/rules/*.md` files. When conditions defined in the rule are met on a PR, Gitar automatically executes the specified actions.

See the [Repository Rules documentation](/features/rules) for full details, syntax, and examples.

## Organization-Level Settings

Repository configuration is complemented by organization-level settings that apply across all repositories. These include enabling/disabling features like code review, managing integrations, and controlling default behaviors.

See [Settings](/configuration/settings) for organization-level configuration options.