Skip to main content
Gitar can hold a merge when review findings meet a configured severity threshold. A separate opt-in setting lets Gitar hold GitLab merges while it reviews qualifying pushes.

Enabling block merge

Only organization admins can configure these settings. Configure finding-based blocks in Settings -> Configuration -> Approvals:
  1. Select Organization defaults or a repository in the scope picker.
  2. Set Behavior under Block merges to the lowest severity that should block a merge.
After each review, Gitar compares the verdict with this threshold. When findings fall below the threshold, Gitar releases its block. Other merge requirements still apply.

Require Gitar before merging

Follow the instructions for the code host to require Gitar to finish processing before merging. Finding-based blocking remains a separate setting.
Require the Gitar status check in a GitHub branch ruleset:
  1. Run Gitar on a PR so the check appears in the repository.
  2. Open Settings -> Rules -> Rulesets and create or edit a ruleset for the target branches.
  3. Enable Require status checks to pass.
  4. Add Gitar as a required check and select the Gitar GitHub App as its expected source.
  5. Set enforcement to Active and save the ruleset.
The check passes when Gitar finishes processing the PR, even if the review has findings, and fails if processing fails. Because the check is required, that failure blocks merging until Gitar processes the PR successfully. Configure Block merges separately to block merging based on finding severity.Apply this requirement where Gitar processes every PR. Excluded PRs can wait for a check that never appears. Existing branch protection rules can also require the check. See GitHub’s required status checks documentation.
GitLab must enforce MR approval rules, generally on Premium or Ultimate. Auto-Approve is not required.
  1. Open Settings -> Configuration -> Approvals and select the organization or repository scope.
  2. Under Block merges, set Behavior to the lowest finding severity that should block merging.
  3. Enable Hold GitLab merges while reviewing pushes under Block merges.
The setting defaults to off. Choosing a severity enables merge blocking, which Gitar needs to place a review hold. With Behavior set to Never, the hold control is disabled.Gitar places the hold when the agent starts reviewing a user push to a tracked, open MR. A tracked MR is one already known to Gitar. Single-commit reverts are exempt.Opening or editing an MR does not create a hold. Neither do CI events or manual review requests. A manual review can retry an existing hold on the same commit.An MR can remain mergeable while work is queued or the agent starts. Enabling the setting does not add holds to existing MRs. MRs opened before installation can remain untracked.When review completes or is skipped, Gitar removes its rule unless findings still require blocking. If findings still require blocking, Gitar keeps the same rule in place so the merge remains blocked throughout.If a review fails, the merge hold remains in place. Request another review to retry, or use the override controls.Turning off this option prevents new review holds. A hold already in progress remains until the review settles or an override releases it.
GitLab’s Gitar status CI job can block a pipeline on stored findings. The job passes for pending and does not check the reviewed commit, so it does not require a review of the MR’s current commit.
Gitar does not integrate with GitLab’s external status checks API. Enabling Status checks must succeed alone does not make an MR wait for Gitar.

Platform behavior

Each host enforces finding-based blocks differently. See Platform support for the capability matrix.
Gitar submits a request-changes review. Branch protection or rulesets must enforce that review for it to block merging.Gitar dismisses its review when the block clears. Repository admins can also dismiss it through GitHub. Gitar respects that override for the current review cycle.
Gitar uses an MR-level approval rule named Gitar and posts a blocking comment. When GitLab does not enforce approval rules, Gitar leaves findings in the review summary and does not claim a merge block.Gitar removes its own rule when the block clears. Submitting an approval is controlled separately by Auto-Approve.
Gitar casts a reject vote. To enforce it, make the connected Gitar account a required reviewer or configure a blocking reviewer policy that does not allow completion with reject votes. A reject vote alone does not guarantee a merge block. See Microsoft’s branch policy documentation.
Gitar records a request-changes status on Cloud and a needs-work status on Data Center. Gitar does not configure or verify repository merge checks. Whether these statuses prevent merging depends on the repository’s merge checks.
Gitar adds a native approval rule while blocking findings remain. When the review clears or an authorized user runs gitar unblock, Gitar removes its own rule. Existing customer approval rules remain in place.

Overriding a block

An override releases Gitar’s block while leaving the code host’s other merge requirements in place. For finding-based blocks, a push alone does not cancel a recorded override. Once a later review clears the configured blocking threshold, Gitar can block again if subsequent findings meet it. Once an admin enables gitar unblock, members can use it without organization admin access. Each successful unblock is logged in a PR comment. The command is unavailable on Bitbucket Data Center.