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

# Configuration Repository

> Share configuration from up to three repositories across your organization

Select up to three configuration repositories. Every repository in the organization inherits their shared configuration.

Gitar reads shared configuration and AI instruction files from each selected repository's default branch alongside the repository under review's own configuration. Teams can keep their shared files in separate repositories.

## Before you begin

* The configuration repository is available on the **Pro** and **Enterprise** plans. It is being rolled out per organization, so [contact support](mailto:support@gitar.ai?subject=Configuration%20repository) if you do not see the picker.
* You need the organization admin role.
* The repository has to be connected to Gitar already. AWS CodeCommit repositories are not selectable.

## What it holds

Shared configuration includes these paths:

| Directory | What it does | Override |
| - | - | - |
| `.gitar/skills/` | [Skills](/integrations/skills) every repository's agents can call | A repository's own skill of the same `name` wins |
| `.gitar/rules/` | [Rules](/features/rules) every repository evaluates | A repository's own rule file of the same name wins (case and `-`/`_` insensitive) |
| `.gitar/review/` | [Review instructions](/configuration/repository-config#custom-review-instructions) applied to every review | Both load, the organization's first |
| `.gitar/instructions/` | Instructions for every Gitar agent | Both load |
| [AI instruction files](/configuration/repository-config#ai-instruction-files), including `CLAUDE.md`, `AGENTS.md` and `.claude/rules/` | Shared conventions for code review and CI failure fixing | Both load, shared instructions first |
| `.gitar/cross-repo.md` | [Cross-repo guidance](/features/cross-repo-analysis) naming dependencies to include or exclude | Both load |
| `.gitar/config/approve.md`, `.gitar/config/merge.md`, `.gitar/config/risk.md` | Shared auto-approve, auto-merge, and risk criteria that extend the organization baseline | Both apply, the repository's own on top. `apply.md` is not shared |

`.gitar/config/apply.md` remains per repository and is not inherited.

Local rules and skills take precedence. Among shared repositories, the first selected repository wins a duplicate rule or skill. The settings list shows that order.

Instruction files combine guidance from every selected repository, followed by local instructions. They share the existing instruction budget, so adding repositories does not multiply that budget. A local instruction file does not replace shared instructions.

All selected repositories apply organization-wide. GitLab group assignments are not supported.

## Set the configuration repository

<Steps>
  <Step title="Create or pick a repository">
    Any connected repository works. A repository named `.gitar` is a clear place for it.
  </Step>

  <Step title="Commit your shared configuration to it">
    The same paths a repository uses for its own:

    ```text theme={null}
    .gitar/
      skills/
        migration-check/
          SKILL.md
      rules/
        no-raw-sql.md
      review/
        gotchas.md
      config/
        approve.md
        merge.md
        risk.md
      instructions/
        conventions.md
      cross-repo.md
    ```

    Add whichever you need. See [Writing a skill](/integrations/skills#writing-a-skill), [Rules](/features/rules) and [Custom review instructions](/configuration/repository-config#custom-review-instructions) for each file format. Push to the default branch.
  </Step>

  <Step title="Name it in settings">
    Go to **Settings -> Configuration**. At the foot of the **Repositories** card, under **Configuration repositories**, select **Add repository** and pick a repository. Repeat for up to three repositories.
  </Step>

  <Step title="Confirm what Gitar found">
    Saving reads the selected repositories and lists discovered skills under each repository. Connection and read failures appear separately for each selection.

    The list shows skills only. Inherited rules and review instructions are not listed on the card, so confirm those on the next run in a repository that inherits them.
  </Step>
</Steps>

Select **Remove** beside a repository to stop inheriting from it. Select **Clear all** to stop inheriting shared configuration.

## Where Gitar looks

Automation rules come from `.gitar/rules/` and custom review instructions from `.gitar/review/`. Both are read recursively, so subdirectories work.

Gitar also reads the same [AI instruction files](/configuration/repository-config#ai-instruction-files) as in a local repository, including `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.cursor/rules/` and `.claude/rules/`. These load automatically from the configuration repository's root. Both rule directories are read one level deep.

Keep shared Claude rules directly in `.claude/rules/`. No symlink to `.gitar/review/` is needed. These files provide instructions, while `.gitar/rules/` defines automation workflows.

Skills have six directories, in this order:

```text theme={null}
your-config-repo/
  .gitar/skills/<name>/SKILL.md
  .claude/skills/<name>/SKILL.md
  .agents/skills/<name>/SKILL.md
  .github/skills/<name>/SKILL.md
  skills/<name>/SKILL.md                     # marketplace layout
  plugins/<plugin>/skills/<name>/SKILL.md    # marketplace layout
```

The first four are the same directories Gitar reads in any repository. See [Where skills live](/integrations/skills#where-skills-live) for the precedence rule.

The last two are the Claude Code and Copilot marketplace layouts, read only in the configuration repository, so a marketplace repository works as-is.

A repository's own copy wins. Commit a skill under `.gitar/skills/` with the same `name` as an inherited one and the local version is what runs.

## When changes take effect

A push to the default branch can take up to 15 minutes to reach the next run.

To test an edit before it lands, open a PR in the configuration repository itself. Gitar reviews that PR against the version on its branch rather than the version on the default branch.

<Warning>
  Anyone who can push to your configuration repository can change what every Gitar agent in your organization does. Skills, rules and review instructions are all instructions the agent follows, and a skill directory can carry scripts the agent runs.

  Protect its default branch the way you protect CI configuration: require review, and restrict who can merge.
</Warning>

## Troubleshooting

| The card says | Cause | Fix |
| - | - | - |
| "disconnected" beside a repository | The repository was disconnected from Gitar after it was named | Reconnect it, or name another repository |
| A read failure reason | Gitar could not fetch the repository | Remove and add the repository again to force a fresh read. Contact support if it persists |
| "No skills found" | Nothing under any of the six skill directories. Rules and review instructions are not counted here, so they may still be loading | Add `.gitar/skills/<name>/SKILL.md` and push, or ignore it if you only share rules and review instructions |

A failed fetch does not fail the review or prevent other selected repositories from loading. The card shows the connection state and the last save-time read.

### An inherited rule never runs

Check the repository under review for a rule file of the same name under `.gitar/rules/`, which takes precedence.

Then check that the repository runs its own rules at all. Inherited rules need the same plan as committed ones, so if `.gitar/rules/` in the repository does nothing, the configuration repository's will not run either.

See [Debugging](/features/rules#debugging) for the rest.

### An inherited skill never runs

Check the repository under review for a skill of the same `name`, which takes precedence. Then check the name against the slugs Gitar holds for [integrations](/integrations/custom-integrations), like `jira`, `linear` and `slack`. A skill named after one is dropped, whether or not you have that integration on, so rename it.

After that, see [Why is my skill not being used?](/integrations/skills#why-is-my-skill-not-being-used).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.