Policy Checks

Codity provides configurable policy checks that enforce merge requirements on pull requests and merge requests. Policies are enforced via commit status checks (codity/policy-check) and can block merges until requirements are met.

Overview

Policy checks run automatically on every PR/MR and report results as a commit status check. When configured as a required status check in your branch protection rules, failing policy checks prevent merging.

Supported Platforms:

• GitHub
• GitLab
• Azure DevOps
• Bitbucket

Available Policy Checks

Minimum Reviewers

Requires a minimum number of unique approvals before a PR/MR can be merged.

• Default: 2 reviewers
• Range: 0–10

Recognized Approval Comments:

• lgtm
• approved
• looks good to me
• looks good
• ship it
• +1

The PR author's own approvals and comments are excluded from the count. Only the latest review per user is considered.

Require Ticket Reference

Requires a ticket reference (e.g., Jira, GitHub issue) in the PR title or body.

• Default: Enabled
• Default Patterns: JIRA-*, ENG-*, #*

Patterns use glob-style matching:

• JIRA-* matches JIRA-123, JIRA-456, etc.
• ENG-* matches ENG-100, ENG-200, etc.
• #* matches #42, #100, etc.

Both the PR title and body are searched for matches.

Require Tests

Requires test files to be included when code files are changed.

• Default: Enabled

Default Test File Patterns:

• **/test/**, **/tests/**
• **/*_test.py, **/test_*.py
• **/*_test.go
• **/*.spec.js, **/*.test.js
• **/*.spec.ts, **/*.test.ts
• **/*.spec.jsx, **/*.test.jsx
• **/*.spec.tsx, **/*.test.tsx
• **/*Test.java
• **/*_test.rb, **/*_spec.rb

Files excluded from test requirement (non-testable):

• Documentation: .md, .rst, .txt
• Configuration: .yml, .yaml, .json, .toml, .ini, .xml, .env
• Styles/Assets: .css, .scss, .svg, .png, .jpg, fonts
• Shell scripts: .sh, .bash, .bat
• Build/CI files: Dockerfile, Makefile, Jenkinsfile, .gitlab-ci.yml
• Lock files: package-lock.json, yarn.lock, go.sum, Gemfile.lock
• Paths: migrations/, .github/, .gitlab/, config/, docs/, vendor/, node_modules/, static/, assets/

If only non-testable files are changed, the check passes automatically.

Require Description Sections

Requires specific sections to be present in the PR description.

• Default: Disabled
• Example Sections: ## Summary, ## Changes, ## Test Plan

Section matching is case-insensitive.

Configuring Policy Checks

Step 1: Open Policy Settings

1. Navigate to Settings in the Codity dashboard
2. Expand the Repository Policies (SOC2 Compliance) section
3. Find your repository in the list
4. Click the Configure button next to the repository

Repositories show a Configured badge if policies are already set, or Not Configured if using defaults.

Step 2: Configure Policies

On the policy settings page for your repository:

1. Minimum Reviewers: Set the number of required approvals (0–10)
2. Require Ticket Reference: Toggle on/off and customize ticket patterns (one pattern per line)
3. Require Test Files: Toggle on/off and customize test file patterns (one pattern per line)
4. Require Description Sections: Toggle on/off and specify required section headings (one per line)

Click Save Policy to apply changes.

Step 3: Enable Branch Protection

For policy checks to block merges, configure your branch protection rules to require the codity/policy-check status check.

GitHub:

1. Go to repository Settings → Branches → Branch protection rules
2. Edit or add a rule for your target branch
3. Enable Require status checks to pass before merging
4. Search for and add codity/policy-check

GitLab: Policy results are posted as commit statuses on merge requests.

Azure DevOps: Policy results are posted as PR statuses.

Bitbucket: Policy results are posted as build statuses on commits.

Org-Wide Policy

You can set a policy that applies across all repositories in your organization. When a repository does not have its own policy configured, it inherits the org-wide policy.

Resolution order:

1. Repository-level policy: if configured, this is used
2. Org-wide policy: used when no repository-level policy exists
3. Built-in defaults: used when neither is set

Configuring Org-Wide Policy

1. Navigate to Settings in the Codity dashboard
2. Expand the Repository Policies section
3. Click Configure Org-Wide Policy
4. Set your desired values and click Save Policy

Changes to the org-wide policy take effect immediately for all repositories that do not have a repository-level policy.

How Results Are Reported

Commit Status Check

Codity posts a codity/policy-check status on the latest commit of the PR/MR:

• Success: All policy checks passed
• Failure: One or more policy checks failed

PR/MR Comment

When policy checks fail, Codity posts a comment on the PR/MR with details:

• Which checks passed
• Which checks failed and why
• What actions are needed to resolve failures

Example failure message:

✗ 2/4 policy checks failed:

  • Need 1 more approval(s) (1/2): comment LGTM or approve via review
  • 3 code file(s) changed but no test files added

✓ 2 checks passed:
  • Found ticket reference(s): JIRA-123
  • All 3 required section(s) present

---

Merge Block on Failed Review

A separate enforcement layer that prevents merges when a Codity review marks a PR/MR as not mergeable (one or more hard-block issues found). When enabled, Codity posts a dedicated status check the host VCS uses to gate the merge button.

This is independent from the policy checks above : policies enforce process requirements (reviewers, tickets, tests), the merge block enforces review quality (security vulnerabilities, critical bugs, blocking issues).

Status Name per Provider

Provider	Status name as displayed in the VCS
GitHub	codity/pr-review
GitLab	codity/pr-review
Azure DevOps	codity/codity/pr-review (genre codity/codity + name pr-review)
Bitbucket	codity/pr-review

Enabling Merge Block

Two settings must both be configured for merges to actually be blocked:

1. Codity dashboard toggle : controls whether Codity posts a failing status on bad reviews.
2. VCS branch protection / branch policy : controls whether your host VCS treats that status as required.

Step 1 : Turn on the Codity toggle

1. Navigate to Settings in the Codity dashboard.
2. Expand the Repository Policies (SOC2 Compliance) section.
3. Find Block PR merge on failed review.
4. Toggle it ON.

The toggle can be set at the organization level (applies to every repo unless overridden) or per-repository.

Step 2 : Configure your VCS to require the status

GitHub

1. Repository Settings → Branches → Branch protection rules → edit or add a rule for your target branch.
2. Enable Require status checks to pass before merging.
3. Type codity/pr-review in the search box and add it as required.
4. To gate admins too, enable Do not allow bypassing the above settings.

> Note: GitHub only shows status contexts in the picker that have been posted at least once on a commit in that repository. If codity/pr-review doesn't appear, open a test PR first so Codity posts the status, then return to settings.

GitLab

1. Project Settings → Merge requests → Merge checks.
2. Enable Pipelines must succeed.

> Note: GitLab enforces commit statuses only when the project has CI configured. If your repo has no .gitlab-ci.yml, the status appears informationally but does not block merges. Add a minimal pipeline (one no-op job that runs true) to activate the gate.

Azure DevOps

1. Project Settings → Repos → Branch policies → select your target branch.
2. Under Status checks click + (add policy).
3. Status to check: type codity/codity/pr-review exactly. Azure parses it into genre codity/codity and name pr-review.
4. Policy requirement: select Required.
5. Policy applicability: select Apply by default.
6. Click Save.

To gate admins as well:

1. Open Repos → Branches, select your branch, and click the Security tab.
2. For each administrative group : Build Administrators, Project Administrators, Project Collection Administrators, Contributors : set Bypass policies when completing pull requests to Deny.

> Common mistake: configuring the policy as codity/pr-review (single codity). Azure stores genre codity/codity and name pr-review : the combined string is what you must type.

Bitbucket Cloud

1. Repository Settings → Branch restrictions → edit the rule for your protected branch.
2. Enable Prevent merge with unresolved merge checks.
3. Add codity/pr-review as a required merge check.

> Note: Hard-prevent enforcement on Bitbucket Cloud requires the Premium plan.

Overriding the Block with /codity-unblock

A reviewer can dismiss the block by commenting on the PR:

/codity-unblock

Optionally with a reason:

/codity-unblock approved by oncall
/codity-unblock reason: investigated, false positive

Rules:

• The PR author cannot override their own PR. A different user (the "two-person rule") must run the command. If the author runs it, Codity replies that the command is rejected.
• The override is scoped to the current head commit SHA. A new push creates a new SHA, invalidates the prior override, and Codity reviews the new commit fresh : if it still finds issues, the PR is re-blocked.
• Once accepted, the status flips to success/succeeded and the merge button enables.
• Re-runs of the review on the same SHA respect the override. If a webhook fires (a new comment, a manual re-trigger) and the review still finds the same issues, Codity will not undo your /codity-unblock : the status stays succeeded until a new commit advances the SHA.

Disabling the Toggle

When you turn the Merge Block toggle OFF:

• The next webhook on a PR causes Codity to post success / succeeded once, clearing any stale failing status from when the toggle was on.
• New PRs are no longer gated by Codity.
• The VCS-side branch policy stays in place. To fully remove gating, also remove or disable the required-status setting in your host VCS.

> If a PR remains blocked after you toggle OFF, push any commit (even a whitespace change) or post /codity-unblock to wake the worker. The worker will then post success and the policy clears.

Audit Trail

Every /codity-unblock invocation is recorded. Settings → Repository Policies → View override audit trail.

Each row contains:

• Platform (github / gitlab / azure / bitbucket)
• Repository
• PR/MR number
• Head commit SHA at the time of override
• Overrider username
• PR author username
• Reason text (if provided)
• Timestamp of the override
• Invalidation timestamp (if a later push or re-block superseded the override)

Override rows are never deleted : invalidated overrides remain visible for compliance review.

Required OAuth / Token Scopes

Provider	Required scope
GitHub	repo (write to commit statuses)
GitLab	api (full API)
Azure DevOps	Code (read & write) + Pull Request Threads (read & write)
Bitbucket	pullrequest:write

If Codity's token is missing the required scope, the status post returns 401/403 and the merge gate fails silently. Re-authorize Codity for the affected provider in Settings → Integrations.

Troubleshooting

Symptom	Likely cause	Fix
Status posts succeed but the merge button isn't gated	VCS-side branch protection / policy not configured	Re-do Step 2 above for your provider
codity/pr-review not in GitHub's required-status picker	No status has been posted to any commit in this repo yet	Open a test PR; Codity posts the status; return to settings
Azure shows "1 required check not yet run" after /codity-unblock	Policy applicability set to Conditional with no prior status, or the status name typed incorrectly	Set policy to Apply by default + Required; verify status name is exactly codity/codity/pr-review
/codity-unblock posts no reply	Commenter doesn't have a Codity OAuth token stored, or PR author is the commenter	Have a different reviewer (one whose VCS account has authorized Codity) run the command
PR still blocked after toggling Codity OFF	Stale failing status; worker hasn't been triggered yet	Push a commit or comment /codity-unblock to trigger the worker; it posts success on the next webhook
GitLab status posts but doesn't block	No pipeline configured in the project	Add a minimal .gitlab-ci.yml so GitLab's "Pipelines must succeed" gate has something to evaluate