Compliance evidence

Auditors testing change management ask the same questions about every change: who wrote it, who approved it, what was checked, what was found and what happened to it. MergeHarbor already knows most of the answers. Compliance evidence collects them for each pull request, checks the pull request against your policies, and seals the result when it merges.

Compliance evidence is part of the Advanced and Enterprise plans.

What a pull request’s evidence contains

• People: who opened the pull request, who approved it on the code host and on which commit, and who merged it (and whether it was merged from the MergeHarbor console).
• What MergeHarbor checked: every review with its tier, the models it used, the categories and built-in checks in force, and the rules that applied.
• Findings and their resolution: fixed in a later commit, marked addressed (by whom), or dismissed (by whom, with the reason and note).
• Proof runs and the requirements check of linked tickets, when you use them.
• Controls: the result of each of your policies, with the details of every check.
• Exceptions: failed controls someone accepted, with their written justification.

Approvals and the merger are read from GitHub and GitLab. On other code hosts they are reported as unavailable, and approval checks fail rather than pass silently.

Sealing

When a pull request merges, MergeHarbor seals its evidence within a few minutes into an append-only ledger. Each record carries the SHA-256 hash of the previous one, so changing, removing or reordering a record breaks the chain. Verify ledger on the Compliance page recomputes it. Turning compliance evidence on also seals pull requests merged in the 30 days before.

Sealed evidence never changes. If a control failed and the change is acceptable, someone with the Manage compliance permission can record an exception with a justification. The exception is added next to the evidence and appears in reports.

Turn it on

Go to Settings → Compliance:

1. Turn on Seal evidence for merged pull requests.
2. Pick the starter packs for the frameworks you report against: SOC 2, ISO/IEC 27001:2022, PCI DSS v4.0.
3. Optionally add your own policies in the editor. Problems are shown with their line as you type.

Every save creates a new policy version; each sealed record names the version it was checked against.

Starter packs

Control	What it requires	SOC 2	ISO 27001	PCI DSS
Peer approval before merge	Someone other than the author approved before merging into the default branch	CC8.1	A.8.32
Independent approval of the final change	The approval was given on the commit that merged			6.2.3.1, 6.5.1
Automated code review of the final change	A MergeHarbor review finished on the commit that merged	CC8.1	A.8.29	6.2.3
No unresolved critical findings	Critical findings were fixed or dismissed with a reason	CC7.1, CC8.1		6.2.3
Security findings resolved	Major and critical security findings were fixed or dismissed with a reason	CC7.1	A.8.28	6.2.4
No hard-coded secrets	Detected secrets were removed (or dismissed as false positives)	CC6.1	A.5.17	8.6.2
Back-out plan for database migrations	A changed migration ships with a rollback, a “Rollback” section in the description, or a label	CC8.1	A.8.32	6.5.1
Linked requirements met (advisory)	No acceptance criterion of a linked ticket was found unmet	CC8.1	A.8.25

References show which requirements the evidence helps support. They are not a certification of your organization or of MergeHarbor, and your auditor decides what evidence a control needs.

Write your own policies

Policies are YAML. Each one says when it applies, what it requires, and which requirements it supports:

version: 1
disable: [migration-backout] # turn off a starter control
policies:
  - id: payments-security-review
    name: Security review for payment code
    severity: blocking # or advisory: reported, never fails the change
    applies_to:
      branches: [$default, "release/*"] # $default is the repository's default branch
      paths: ["payments/**"]
    require:
      - review_completed: { min_tier: deep }
      - approvals: { min: 1, from_teams: [security] }
      - no_open_findings: { min_severity: major, categories: [security] }
    frameworks:
      pci_dss: ["6.2.4"]

Reusing a starter control’s id replaces it. The checks:

Check	Options	Passes when
approvals	min, exclude_author (default true), on_final_commit, from_teams	Enough people approved on the code host; automation accounts never count
no_open_findings	min_severity (default critical), categories, dismissals_need_reason	No finding at that severity is still open
review_completed	on_final_commit (default true), min_tier	A MergeHarbor review finished on the commit that merged
category_reviewed	category, min_severity (default major)	The review covered the category and left no unresolved findings in it
no_secrets		Every detected secret was removed or dismissed as a false positive
migration_rollback	paths, rollback, or_label, or_section	Changed migrations come with a rollback, a rollback section or a label
proof_run	outcomes (default passed), on_final_commit	The latest proof run ended as required
requirements_met	allow_unclear, require_linked	No acceptance criterion of a linked ticket is unmet
labels	any_of	The pull request has one of the labels
merge_gate		The merge gate passed or was overridden

Policies in a repository

A repository can add its own policies in a compliance: block of the root .mergeharbor.yml. They are read from the base branch, so a pull request cannot change the policies it is checked against, and they cannot turn off or replace your organization’s policies.

compliance:
  policies:
    - id: schema-rollback
      require:
        - migration_rollback: { paths: ["db/schema/**"], rollback: ["db/rollback/**"] }

On the pull request

The Compliance tab of a pull request in the console shows how it does against your policies while it is open, and its sealed record after it merges. Download the evidence as PDF (for people) or JSON (complete, for tools).

Reports for auditors

On Settings → Compliance, filter by period, repository, status or control to see pass rates and every sealed change. Request report builds a ZIP in the background with:

• the population: every pull request merged in the period, with its evidence status, approvers, merger and record hash;
• a random sample of the size you choose. The seed is recorded (reuse it to draw the same sample), and the method is described in the manifest so anyone can redraw it from the population;
• pass rates per control and every exception with its justification;
• the full sealed evidence of each sampled change, and a PDF with the same content;
• a manifest listing the SHA-256 of every file, a SHA256SUMS file for sha256sum -c, and MergeHarbor’s signature of the manifest.

Reports are kept for 30 days; download links last 15 minutes. Self-hosted installations need object storage for reports.

Permissions

• View compliance evidence (compliance.read): the Compliance tab, the Compliance page, policies and reports. Included in the Owner, Admin, Member and Viewer roles; you can create an Auditor role with only this permission.
• Manage compliance (compliance.manage): change policies and record exceptions. Owners and admins.

Policy changes, exceptions, exports, report requests and downloads, and ledger verifications are recorded in the audit log (Settings → Audit log).