Skip to content

Quick-Win Quality Gates — Self-Service Adoption Guide

Package: Quick-Win Entry [QW] · Milestone: M1 · Time-to-value: 2–3 days Ownership: [CA] Client-Adopted — SnowOps configures once, your team runs it thereafter. Cloud credentials required: None. These gates run entirely in your Git/CI; they never touch your cloud.

What You Get

A portable set of pre-merge quality and security gates that drop onto any existing repository with zero new infrastructure. They block insecure or non-compliant changes before they ever reach your default branch — the fastest path to demonstrable security hygiene for an auditor or an enterprise customer's security questionnaire.

Asset What it does Where it runs
D1 — .pre-commit-config.yaml Local pre-commit/pre-push hooks: terraform fmt, tflint, checkov, tfsec, gitleaks, trivy fs, conftest verify Developer laptop
D2 — quality-gates.yml PR-blocking GitHub Actions mirror of D1 — the server-side enforcement so the gate can't be skipped GitHub Actions
D3 — OPA/Conftest bundle Policy-as-code over terraform plan JSON: encryption, mandatory tags, no public network, allowed regions, cost caps CI (post-plan) + pre-push
C4 — Branching standard + template GitOps branching convention, CODEOWNERS, branch-protection rules GitHub repo settings
R1 — PR template + required-fields check Enforces a structured PR description (change type, risk, rollback) GitHub Actions

These five are the contents of the Quick-Win Entry package (§3.1 of the service catalog). They are the same gates SnowOps runs on its own codebase.

Prerequisites

  • A Git repository (GitHub for the full PR-gating experience; D1 + D3 work on any Git host).
  • Local tooling for developers running D1: pre-commit, terraform ≥ 1.6, tflint, checkov, tfsec, gitleaks, trivy, conftest. (D1's config installs the hook managers; the binaries are documented in the template README.)
  • Repo admin rights to configure branch protection (C4) — one-time, by a repo owner.
  • No cloud credentials. Nothing here authenticates to Azure/AWS/GCP.

Adoption — Three Steps

Step 1 — Drop in the gates (Day 1)

Copy the four config artifacts from the SnowOps client-repo template (templates/client-repo/) into your repository root:

.pre-commit-config.yaml                      # D1
.github/workflows/quality-gates.yml          # D2
.github/workflows/pr-template-check.yml      # R1
.github/PULL_REQUEST_TEMPLATE.md             # R1
.github/CODEOWNERS                           # C4

The OPA policy bundle (D3) is consumed by reference — point conftest at the SnowOps policy/opa/rules bundle (pin to a tag), or vendor a copy if you need to run air-gapped.

Install the local hooks:

pre-commit install            # pre-commit stage
pre-commit install --hook-type pre-push   # conftest verify on push

Step 2 — Turn on branch protection (Day 1–2)

Apply the C4 branching standard (docs/conventions/branching.md) to your default branch:

  • Require pull requests before merging; squash-merge only.
  • Require status checks to pass: quality-gates, pr-template-check.
  • Require a CODEOWNER review.
  • Dismiss stale approvals on new commits; no force-push to the protected branch.

These map 1:1 to the rules in templates/client-repo/README.md.

Step 3 — Verify the gate actually blocks (Day 2–3)

Prove the gates work before you trust them. Open three throwaway PRs:

Test PR Expected result
Commit a hardcoded secret (e.g. a fake AZURE_CLIENT_SECRET=...) Blocked by gitleaks (D1 locally + D2 in CI)
A terraform resource with a public network rule / missing required tag Blocked by the D3 OPA bundle at the conftest step
A PR with an empty description Blocked by pr-template-check (R1)

A clean PR with a well-formed description and a compliant plan should pass all checks and be mergeable. That round-trip is your acceptance test.

How This Maps to Compliance

These gates produce auditor-relevant evidence on day one — without any cloud footprint:

Control theme Framework reference Evidence produced
Change management — peer review enforced SOC 2 CC8.1 · ISO 27001 A.8.32 Branch-protection settings + merged-PR history with approvals
Secure development — secrets never committed SOC 2 CC6.1 · ISO 27001 A.8.24 gitleaks CI run history
Secure development — IaC scanned pre-merge SOC 2 CC7.1 · ISO 27001 A.8.28 checkov/tfsec/conftest CI logs
Change documentation SOC 2 CC8.1 PR template required-fields enforcement (R1)

See compliance/soc2/control-mapping.md and compliance/iso27001/control-mapping.md for the full mapping. These gates are the foundation the Baseline and Advanced packages build on.

Failure Modes & Support

Symptom Likely cause Fix
conftest step fails on an existing resource you can't change yet A real violation in pre-existing infra Use a D5 time-boxed waiver (waivers/exceptions.yaml) — see the Brownfield Adoption guide. Don't disable the rule.
Local hooks pass but CI fails Tool version skew between laptop and runner Pin tool versions; the template README lists the supported versions.
Developers bypass hooks with --no-verify Local hooks are advisory; server-side D2 is the real gate This is by design — D2 in CI cannot be skipped because branch protection requires the check.
OPA bundle reports a rule you disagree with Policy mismatch with your risk posture Rules are tunable; raise it with SnowOps. Do not edit the bundle in place without re-running the D3 conftest test suite (X3).

Removal Path

This package is purely additive and fully reversible:

  1. Delete the copied workflow/config files.
  2. Remove the required status checks from branch protection (or relax the rules).
  3. pre-commit uninstall.

No cloud resources were created, so there is nothing to terraform destroy. Your repository history and code are untouched.

Where to Go Next

The Quick-Win gates are the wedge. The natural expansion path: