> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qodo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom compliance

<Badge color="outline-provider" size="sm" shape="pill" icon="github">GitHub</Badge>
<Badge color="outline-provider" size="sm" shape="pill" icon="gitlab">GitLab</Badge>
<Badge color="outline-provider" size="sm" shape="pill" icon="bitbucket">Bitbucket</Badge>

Custom compliance allows you to define and enforce requirements on pull requests, such as security checks, ticket validation, and organizational policies.

## Set up custom compliance

Each compliance is defined in a YAML file with the following fields:

* `title` (required): A clear, descriptive title that identifies what is being checked.
* `compliance_label` (required): Determines whether this compliance generates labels for non-compliance issues (`true` or `false`).
* `objective` (required): A detailed description of the goal or purpose of the compliance.
* `success_criteria` / `failure_criteria` (at least one required): Define the conditions for compliance.

<AccordionGroup>
  <Accordion title="Example of a compliance checklist">
    ```bash theme={null}
    # pr_compliance_checklist.yaml
    pr_compliances:
      - title: "Error Handling"
        compliance_label: true
        objective: "All external API calls must have proper error handling"
        success_criteria: "Try-catch blocks around external calls with appropriate logging"
        failure_criteria: "External API calls without error handling or logging"

    ...
    ```
  </Accordion>

  <Accordion title="Writing effective compliance checklists">
    * Avoid overly complex or subjective compliances that are hard to verify.
    * Keep compliances focused on security, business requirements, and critical standards.
    * Use clear, actionable language that developers can understand.
    * Focus on meaningful compliance requirements, not style preferences.
  </Accordion>

  <Accordion title="Ready-to-use compliance templates">
    For production-ready compliance checklist templates organized by programming languages and technology stacks, check out the [PR Compliance Templates repository](https://github.com/qodo-ai/pr-compliance-templates).
  </Accordion>
</AccordionGroup>

## Local compliance checklists

Create a `pr_compliance_checklist.yaml` file in your repository root containing your compliance requirements.

Qodo will use this file during code review. If the PR violates these requirements, the results will be surfaced in the code review.

## Global hierarchical compliance

For organizations managing multiple repositories with different requirements, Qodo supports a hierarchical compliance system using a dedicated global configuration repository.

### Set up global hierarchical compliance

<Steps>
  <Step>
    Create a new repository named `pr-agent-settings` in your organization or workspace.
  </Step>

  <Step>
    Build the folder hierarchy in your `pr-agent-settings` repository. For example:

    ```bash theme={null}
    pr-agent-settings/
    ├── metadata.yaml                              # Maps repos/folders to compliance paths
    └── codebase_standards/                        # Root for all compliance definitions
        ├── global/                                # Global compliance, inherited widely
        │   └── pr_compliance_checklist.yaml
        ├── groups/                                # For groups of repositories
        │   ├── frontend_repos/
        │   │   └── pr_compliance_checklist.yaml
        │   ├── backend_repos/
        │   │   └── pr_compliance_checklist.yaml
        │   ├── python_repos/
        │   │   └── pr_compliance_checklist.yaml
        │   ├── cpp_repos/
        │   │   └── pr_compliance_checklist.yaml
        │   └── ...
        ├── repo_a/                                # For standalone repositories
        │   └── pr_compliance_checklist.yaml
        ├── monorepo-name/                         # For monorepo-specific compliance
        │   ├── pr_compliance_checklist.yaml       # Root-level compliance
        │   ├── service-a/                         # Subproject compliance
        │   │   └── pr_compliance_checklist.yaml
        │   └── service-b/                         # Another subproject
        │       └── pr_compliance_checklist.yaml
        └── ...
    ```

    <Note>
      `pr-agent-settings`, `codebase_standards`, `global`, `groups`, `metadata.yaml`, and `pr_compliance_checklist.yaml` must be named exactly as shown.

      All other names (such as `frontend_repos`, `backend_repos`, etc.) are examples and should be replaced with your actual repository and service names.
    </Note>

    <Accordion title="Grouping and categorizing compliance checklists">
      * Each folder (including the global folder) can contain a single `pr_compliance_checklist.yaml` file.
      * Organize repository compliance checklists by creating subfolders within the `groups` folder.
      * Group them by purpose, programming language, or other categories.
    </Accordion>
  </Step>

  <Step>
    Define the metadata file `metadata.yaml` in the root of `pr-agent-settings`:

    ```bash theme={null}
    # Standalone repos
    qodo-merge:
      pr_compliance_checklist_paths:
        - "qodo-merge"

    # Group-associated repos
    repo_b:
      pr_compliance_checklist_paths:
        - "groups/backend_repos"

    # Multi-group repos
    repo_c:
      pr_compliance_checklist_paths:
        - "groups/frontend_repos"
        - "groups/backend_repos"

    # Monorepo with subprojects
    qodo-monorepo:
      pr_compliance_checklist_paths:
        - "qodo-monorepo"
      monorepo_subprojects:
        frontend:
          pr_compliance_checklist_paths:
            - "qodo-monorepo/qodo-github"
        backend:
          pr_compliance_checklist_paths:
            - "qodo-monorepo/qodo-gitlab"
    ```
  </Step>

  <Step>
    Set the following configuration:

    ```bash theme={null}
    [pr_compliance]
    enable_global_pr_compliance = true
    ```

    <Accordion title="Compliance checklist loading strategy">
      1. **Global checklists**: Hierarchical compliance from the `pr-agent-settings` repository.
         * If the repository is mapped in `metadata.yaml`, it uses the specified paths and the global compliance checklist.
         * For monorepos, it automatically collects compliance checklists matching PR file paths.
         * If the repository is not mapped in `metadata.yaml`, global checklists are not loaded.

      2. **Local repository checklist**: `pr_compliance_checklist.yaml` file in the repository.
         * Loaded if present in the repository.
         * Content is merged with global checklists (if loaded) to create the final compliance checklist.
    </Accordion>
  </Step>
</Steps>

## Configuration options

<AccordionGroup>
  <Accordion title="General options">
    | Option                                  | Description                                                                                                                                                   |
    | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `extra_instructions`                    | Optional extra instructions. For example: "Ensure that all error-handling paths in the code contain appropriate logging statements". Default is empty string. |
    | `persistent_comment`                    | If set to true, the compliance comment will be persistent, meaning that every new compliance request will edit the previous one. Default is true.             |
    | `enable_user_defined_compliance_labels` | If set to true, the label `Failed compliance check` will be added for custom compliance violations. Default is true.                                          |
    | `enable_estimate_effort_to_review`      | If set to true, the estimate effort required to review the PR (1–5 scale) is added as a label. Default is true.                                               |
    | `enable_todo_scan`                      | If set to true, scans for TODO comments in the PR code. Default is false.                                                                                     |
    | `enable_update_pr_compliance_checkbox`  | If set to true, an update checkbox to refresh compliance status following push events will be added. Default is true.                                         |
    | `enable_help_text`                      | If set to true, help text will be displayed in the comment. Default is false.                                                                                 |
  </Accordion>

  <Accordion title="Security compliance options">
    | Option                              | Description                                                                                                                               |
    | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
    | `enable_security_compliance`        | If set to true, checks for security vulnerabilities. Default is true.                                                                     |
    | `enable_compliance_labels_security` | If set to true, a `Possible security concern` label will be added to the PR when security-related concerns are detected. Default is true. |
  </Accordion>

  <Accordion title="Ticket compliance options">
    | Option                        | Description                                                                                         |
    | ----------------------------- | --------------------------------------------------------------------------------------------------- |
    | `enable_ticket_labels`        | If set to true, adds ticket compliance labels to the PR. Default is false.                          |
    | `enable_no_ticket_labels`     | If set to true, adds a label when no ticket is found. Default is false.                             |
    | `check_pr_additional_content` | If set to true, checks whether the PR contains content not related to the ticket. Default is false. |
  </Accordion>
</AccordionGroup>

## Use cases

### Blocking PRs based on compliance

You can configure CI/CD Actions to prevent merging PRs with specific compliance labels:

* `Possible security concern`: Block PRs with potential security issues.
* `Failed compliance check`: Block PRs that violate custom compliance checklists.

Implement a dedicated [GitHub Action](https://medium.com/sequra-tech/quick-tip-block-pull-request-merge-using-labels-6cc326936221) to enforce these checklists.