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

# Best practices for working with Gitar

> Evaluate Gitar on representative pull requests, provide project context, and assess findings and fixes.

Use these practices to evaluate Gitar on representative pull requests, provide useful project context, and assess review findings and fixes.

This guide assumes your repository is connected to Gitar. Start with [Quickstart](https://docs.gitar.ai/quickstart.md) if you have not connected it. Feature availability depends on your [plan](https://docs.gitar.ai/account-billing/plans.md). Knowledge, functional validation, cross-repo analysis, and configurable review depth require Enterprise.

## Start with a representative pull request

Choose a focused change that your team understands and can validate. Use a pull request with clear expected behavior and checks you can run.

For your first evaluation:

1. Open a pull request in a connected repository. If automatic processing is disabled, comment `gitar review`.
2. Read the review verdict and individual findings in Gitar's dashboard comment.
3. Reply to a finding with a question or relevant project context.
4. Request a fix for a finding you agree with by replying `gitar fix`.
5. Inspect the resulting commit and run the appropriate checks.

Check whether each finding explains a real concern and whether the fix preserves the intended behavior. A useful review does not need to produce a particular number of comments.

Evaluate several representative changes before drawing conclusions. Include work that reflects your team's normal development, such as a behavior change or a CI failure.

The [Gitar blueprints](https://www.sonarsource.com/developers/blueprints/?artdisc_category=Gitar) provide worked examples for exploring specific capabilities.

## Choose when Gitar starts processing

Set review scope to match the repositories and workflows you want to evaluate.

| Goal | Gitar control |
| - | - |
| Start processing selected PRs on demand | Enable **Disable automatic processing**, then request a review with `gitar review` or **Start Review** in the dashboard. |
| Wait until draft work is ready | Enable **Skip drafts**. |
| Limit automatic processing by destination branch | Configure **Allowed target branches** or **Excluded target branches**. These refer to the branch the PR merges into. |
| Include dependency updates or other bot-authored changes | Add the bot accounts under **Allowed bots**. Bot-authored changes are skipped by default. |
| Skip automatic processing for one PR | Apply `gitar-skip` before processing starts. Explicit commands still work. |

Disabling automatic processing controls how work starts. Once a requested review has an active run, later pushes and CI failures continue processing. A CI failure that occurred before the initial request needs an explicit request such as `gitar fix CI`.

Behavior settings can have organization defaults and repository overrides. Author and target-branch scope filters apply across the organization.

See [Organization settings](https://docs.gitar.ai/configuration/settings.md), [Labels](https://docs.gitar.ai/labels.md), and [Commands and interactions](https://docs.gitar.ai/commands.md) for configuration details.

## Describe the intended behavior

Explain the problem, expected behavior, and constraints in the pull request. Include how you tested the change.

For example:

> Reject expired invitation links. Valid links must continue to work, and existing members must retain access. Added tests for valid and expired links.

Keep unrelated work in separate pull requests where practical. Focused changes make findings and fixes easier to assess, even though Gitar supports large pull requests.

When requesting a change, name the outcome and any behavior that must stay unchanged:

```text theme={null}
gitar add a regression test for expired invitation links. Keep the existing response format.
```

See [Code Review](https://docs.gitar.ai/features/code-review.md) for review behavior and [Commands and interactions](https://docs.gitar.ai/commands.md) for ways to address Gitar.

## Write linked issues with assessable objectives

For Enterprise functional validation, link the issue the PR is intended to implement and describe its requirements as concrete outcomes.

For example:

> Expected behavior:
>
> * Invitation links expire after 24 hours.
> * An expired link returns the existing invalid-invitation response.
> * An unexpired link still lets the recipient join.
> * Existing members retain access.

Connect the relevant tracker integration when required. Supported linking formats depend on the issue source. Azure DevOps work items attached to the PR are picked up directly.

Gitar assesses each objective against the code changes. Inspect uncovered objectives to determine whether they are missing or intentionally outside this PR's scope.

Objective coverage does not establish that runtime tests ran. Uncovered objectives do not block merging, and separate PRs against the same issue do not produce a combined per-issue completion view.

See [Functional validation](https://docs.gitar.ai/features/functional-validation.md) for supported issue sources, linking instructions, and coverage limits.

## Add targeted instructions after observing reviews

Use actual review results to identify missing project context. Add instructions when a recurring concern depends on a convention Gitar needs to understand.

Name the applicable files or subsystem, state the convention, and explain why it matters.

For example:

> In `src/routes/`, return errors through `sendError()` from `src/lib/http.ts`. Clients expect the shared error envelope. Success responses can use `res.json()` directly.

Choose the instruction source that fits the requirement:

| Requirement | Where to put it |
| - | - |
| A convention specific to code review | Markdown files under `.gitar/review/`. |
| Repository conventions shared with other AI tools | Supported instruction files such as `AGENTS.md`. |
| Guidance for every Gitar agent | Markdown files under `.gitar/instructions/`. |
| Guidance across connected repositories | Organization custom instructions or a configuration repository. |
| An explicit check or action triggered by a PR condition | A rule under `.gitar/rules/`. |

Keep one canonical source for each convention and remove contradictory guidance. If your standards already live in another repository file, use an `@` file reference from a supported instruction file to include them instead of maintaining a second copy.

For example, in `AGENTS.md`:

```text theme={null}
Follow the API conventions in:

@docs/api-conventions.md
```

Instructions can combine across sources. Repository instructions do not automatically replace shared organization guidance. Behavior overrides and automation criteria follow their own rules, so check the relevant configuration guide before relying on precedence.

See [Repository customization](https://docs.gitar.ai/configuration/repository-config.md) for supported files and include syntax. For a worked example, see [Gitar context ingestion for project-aware code reviews](https://www.sonarsource.com/developers/blueprints/gitar-context-ingestion-for-project-aware-code-reviews/).

## Review shared configuration before distributing it

Use a configuration repository when several repositories need the same guidance, rules, or skills.

Review shared changes carefully because they affect every repository that inherits them. Protect the configuration repository's default branch and restrict who can merge changes.

Check inheritance behavior before adding a local exception. Local rules and skills can replace matching shared definitions, while review instructions combine. Shared configuration is read from the configuration repository's default branch.

See [Configuration repository](https://docs.gitar.ai/configuration/configuration-repository.md) for supported files, override behavior, and how to test changes.

## Tune review depth to your team's needs

Enterprise organization admins can choose **Focused** or **Thorough** review depth.

| Setting | Use it when |
| - | - |
| Focused | The team wants to prioritize higher-impact findings. |
| Thorough | The team wants smaller verified issues included and has capacity to assess more comments. |

Set the organization default under **Settings -> Configuration -> Review depth**. Use **Customize** on a repository to override that default. Changes apply on the next review.

If Thorough reviews are disabled for the organization, select **Enable Thorough reviews** before choosing a depth.

If a finding is incorrect, explain the missing context. Changing review depth does not correct an inaccurate convention.

See [Code Review](https://docs.gitar.ai/features/code-review.md#review-depth) for review-depth behavior.

## Explain corrections and temporary exceptions

Reply directly to a finding when your explanation concerns that issue. Identify the relevant code and why the finding does not apply.

For example:

> These handlers run behind the authentication middleware in `src/auth/`. Token validation happens before requests reach this code.

Distinguish lasting conventions from temporary exceptions:

> This compatibility handler is temporary during the migration. The exception applies only to `src/legacy/import.ts` until that handler is removed. Other routes must continue using the shared error format.

With Enterprise Knowledge enabled, explanations can inform later reviews. A dismissal without an explanation does not, by itself, establish a reusable convention.

Inspect the stored guidance in Knowledge. Check its scope and source, then examine recorded use in later reviews. Administrators can mark obsolete entries stale to remove them from future retrieval while retaining their history.

See [Knowledge](https://docs.gitar.ai/features/knowledge.md) for learning behavior and management. The [Gitar Knowledge walkthrough](https://www.sonarsource.com/developers/blueprints/gitar-knowledge/) shows an example across multiple PRs.

## Distinguish a resolved finding from a completed fix

Check how a finding was resolved before treating the underlying issue as fixed.

Gitar can resolve findings after an explanation, an acknowledgement, or a decision to defer work. Those outcomes do not necessarily include a code change.

If you defer a fix, record the follow-up in your team's tracking system and assign an owner.

See [Providing feedback](https://docs.gitar.ai/features/code-review.md#providing-feedback) for how replies and thread actions affect findings.

## Expand automation after checking individual fixes

Request fixes individually during your initial evaluation:

```text theme={null}
gitar fix
```

Inspect the resulting commit and run the appropriate checks before expanding automation.

When enabling auto-apply, define which review findings Gitar may fix. For example:

> Only fix unused imports and formatting. Skip payment logic.

Organization and repository auto-apply review criteria must both be satisfied when both are present. Those criteria govern automatic fixes for review findings. CI fixes and explicit fix requests operate independently of them.

Auto-approve and auto-merge have separate controls. Keep required CI checks enforced through your code host. Natural-language approval criteria are not a substitute for those checks.

See [Auto-Apply](https://docs.gitar.ai/features/code-review/auto-apply.md), [Auto-Approve](https://docs.gitar.ai/features/code-review/auto-approve.md), and [Auto-Merge](https://docs.gitar.ai/features/code-review/auto-merge.md) for criteria and platform requirements.

## Write focused rules and test their behavior

Keep each rule focused on one outcome. Name the paths and conditions that trigger it, describe the expected result, and include relevant exceptions.

Use review instructions for conventions Gitar should consider during code review. Use rules for explicit checks or automated actions.

Test a rule on a dedicated pull request that matches its condition. Also test a change that should fall outside its scope. Confirm the expected result, then inspect why the rule matched or was skipped:

```text theme={null}
gitar display:verbose
```

Check overlapping rules for conflicting actions. Narrow their conditions or consolidate them when they express competing requirements.

See [Repository rules](https://docs.gitar.ai/features/rules.md#best-practices) for writing guidance and examples. The [context ingestion blueprint](https://www.sonarsource.com/developers/blueprints/gitar-context-ingestion-for-project-aware-code-reviews/) includes a worked example of testing a rule.

## Use CI analysis to guide repairs

Read the root-cause analysis before requesting a fix. Explain constraints such as environment requirements or values that must remain unchanged.

For example:

```text theme={null}
gitar fix CI. Keep the integration test timeout unchanged.
```

Connect any CI service that requires separate credentials so Gitar can read its logs. If you provide additional logs, include the relevant excerpt and remove credentials or other sensitive information.

After a fix, inspect the changes and confirm that CI passes on the updated commit.

See [CI failure analysis](https://docs.gitar.ai/features/ci-failure-analysis.md) for connection requirements, unrelated-failure retries, and recovery limits.

## Evaluate changes across repository boundaries

If your Enterprise evaluation includes shared APIs or other contracts, include a representative change and inspect the affected repositories reported by Gitar.

Cross-repo context builds as Gitar reviews connected repositories, so initial reviews may have limited context. When relationships need clarification, use `.gitar/cross-repo.md` to describe dependencies, contracts that must stay consistent, and repositories to exclude.

Inspect where each finding says the fix belongs. Some changes require work in the PR under review, some need a downstream follow-up, and others need coordinated changes.

See [Cross-repo analysis](https://docs.gitar.ai/features/cross-repo-analysis.md) for coverage expectations and relationship guidance.

## Evaluate usefulness alongside activity

Agree on what a useful evaluation should demonstrate before reviewing the results.

| Evaluation question | Evidence to inspect |
| - | - |
| Did Gitar identify actionable concerns? | Sample findings and assess their accuracy, relevance, and severity with the team. |
| Were the fixes correct? | Inspect generated commits and test results. |
| Did project context affect later reviews? | Check Knowledge sources, citations, and recorded use where available. |
| Did rules perform the intended actions? | Inspect rule results and applicability explanations. |
| What remained unresolved? | Review open, dismissed, and acknowledged findings separately from fixes. |

Use [Insights](https://docs.gitar.ai/features/insights.md) to examine activity and resolution patterns within a consistent repository scope and date range, then inspect individual examples behind the totals.

Review counts can include repeated reviews of the same PR. Resolution rates can include acknowledgements without code changes. Neither measure alone establishes how many defects were fixed.

Before merging any evaluated change, inspect the final diff and confirm that your code host's required checks and review requirements are satisfied.


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