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:- Open a pull request in a connected repository. If automatic processing is disabled, comment
gitar review. - Read the review verdict and individual findings in Gitar’s dashboard comment.
- Reply to a finding with a question or relevant project context.
- Request a fix for a finding you agree with by replying
gitar fix. - Inspect the resulting commit and run the appropriate checks.
Choose when Gitar starts processing
Set review scope to match the repositories and workflows you want to evaluate.
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, Labels, and Commands and interactions 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:
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: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 for supported issue sources, linking instructions, and coverage limits.
- 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.
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:InChoose the instruction source that fits the requirement:src/routes/, return errors throughsendError()fromsrc/lib/http.ts. Clients expect the shared error envelope. Success responses can useres.json()directly.
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:
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 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.
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 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 for learning behavior and management. The Gitar Knowledge walkthrough 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 for how replies and thread actions affect findings.Expand automation after checking individual fixes
Request fixes individually during your initial evaluation: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, Auto-Approve, and Auto-Merge 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: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: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 for coverage expectations and relationship guidance.
Evaluate usefulness alongside activity
Agree on what a useful evaluation should demonstrate before reviewing the results.
Use Insights 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.