ci: add Trivy scan, coverage gate, and branch protection docs

[twchichi]

Summary

• Add Trivy Docker image vulnerability scanner to release.yml (blocks on CRITICAL/HIGH)
• Add Trivy filesystem/misconfig scan to release.yml
• Add pytest-cov to test pipeline and enforce 80% coverage threshold
• Document branch protection requirements and required status checks in CONTRIBUTING.md

Test plan

• Verify Trivy scan step runs on next release tag
• Verify test suite fails if coverage drops below 80%
• Confirm CONTRIBUTING.md branch protection table is accurate

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR introduces Trivy vulnerability scanning to the release pipeline, adds a pytest-cov coverage gate to the test matrix, and documents branch protection rules in CONTRIBUTING.md. All three changes have correctness issues that need to be addressed before merging.

• tests.yml: --cov-fail-under=80 is applied to each sharded job, but a shard only runs ~33% of tests — per-shard coverage will never reach 80%, immediately breaking all 9 matrix jobs.
• release.yml: Both Trivy steps are pinned to @master (supply-chain risk with contents: write permissions), and the image scan runs after the image is already pushed, so a vulnerable image remains in GHCR even when the job fails.
• CONTRIBUTING.md: The branch protection table references four workflow files (dep-audit.yml, security-scan.yml, lint-configs.yml, feature-checks.yml) that do not exist in the repository.

Confidence Score: 2/5

Not safe to merge — the coverage gate will break the entire test matrix immediately, the Trivy action is pinned to a floating @master ref with write permissions, and the documentation describes checks backed by non-existent workflow files.

The coverage threshold applied per-shard will cause all 9 matrix jobs to fail on the very next PR. The @master pin on the Trivy action gives an external repository write access to releases and the container registry. The branch protection table in CONTRIBUTING.md lists four workflows that do not exist, making the docs actively misleading.

All three changed files need attention: tests.yml for the broken coverage gate, release.yml for the scan ordering and action pinning, and CONTRIBUTING.md for the phantom workflow references.

Security Review

• Supply-chain injection (release.yml lines 61, 71): Both Trivy steps use aquasecurity/trivy-action@master. Any commit to that third-party repo's master branch executes immediately with the release job's contents: write / packages: write permissions — sufficient to tamper with releases and push malicious images to GHCR. Actions should be pinned to an immutable commit SHA.
• Vulnerable image published before gate fires (release.yml lines 60–68): The Docker image is pushed to the public registry before the Trivy scan runs. A build with CRITICAL CVEs fails the job but the image remains accessible, defeating the intended protection.

Important Files Changed

Filename	Overview
.github/workflows/release.yml	Adds two Trivy scan steps; both pinned to @master (supply-chain risk), and the Docker image scan runs after push so a vulnerable image is already in GHCR before the blocking exit-code=1 gate fires.
.github/workflows/tests.yml	Adds pytest-cov and --cov-fail-under=80 to every sharded matrix job; each shard only runs ~33% of tests so the 80% threshold will never be met, breaking all 9 matrix jobs.
CONTRIBUTING.md	Adds branch protection documentation table that references four workflow files (dep-audit.yml, security-scan.yml, lint-configs.yml, feature-checks.yml) that do not exist in the repository.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub Push (tag)
    participant Build as build-push-action
    participant GHCR as ghcr.io Registry
    participant TrivyImg as Trivy (image scan)
    participant TrivyFS as Trivy (fs/misconfig)

    GH->>Build: push tag trigger release job
    Build->>GHCR: push image (push: true) image now live
    Build-->>GH: image published
    GH->>TrivyImg: scan ghcr.io image for CRITICAL/HIGH
    alt vulnerabilities found
        TrivyImg-->>GH: exit-code 1 job fails
        Note over GHCR: image remains in registry
    else clean
        TrivyImg-->>GH: exit-code 0 continue
    end
    GH->>TrivyFS: fs scan for misconfig (exit-code 0, informational)
    TrivyFS-->>GH: report only

Loading

_{Reviews (1): Last reviewed commit: "ci: add Trivy scan, coverage gate, and b..." | Re-trigger Greptile}

[greptile-apps]

Coverage gate fires on every shard independently, guaranteeing failures

--cov-fail-under=80 is applied to each individual shard, but each shard executes only ~33% of the test suite. Coverage measured against a partial run will almost never reach 80%, so every one of the 9 matrix jobs (3 Python versions × 3 shards) will fail immediately. The threshold should be checked against a merged, full-suite report — either remove --cov-fail-under from the shard command and add a separate upload/merge step, or only apply the gate to a non-sharded job.

[greptile-apps]

Vulnerable image is already published before the blocking scan runs

The docker/build-push-action step at line 48 sets push: true, meaning the image is already in GHCR before the Trivy scan starts. If CRITICAL/HIGH findings are detected, the job exits with code 1 — but the image remains publicly accessible in the registry. The PR description says this "blocks on CRITICAL/HIGH," which is misleading; it blocks the job but does not retract the image. Consider building first with push: false, scanning the local image, and only pushing if the scan is clean.

[greptile-apps]

Action pinned to @master — supply-chain risk

Both Trivy steps use aquasecurity/trivy-action@master. Any commit pushed to the master branch of that third-party repository will execute immediately in this workflow without review. GitHub's own hardening guide and OpenSSF Scorecard recommend pinning actions to an immutable commit SHA or at minimum a version tag. @master means a compromised upstream can inject arbitrary code into every release pipeline, which holds contents: write and packages: write permissions.

[greptile-apps]

Branch protection table references workflows that don't exist

Four of the seven listed required checks point to workflow files not present in .github/workflows/: dep-audit.yml, security-scan.yml, lint-configs.yml, and feature-checks.yml. Only tests.yml, release.yml, and browser-smoke.yml actually exist. The table should only list checks backed by real workflow files, or the missing workflows should be added in this PR.

[nesquena-hermes]

Confirming the three findings + a concrete fix for the coverage gate and the docs table

Read the full diff plus tests.yml and release.yml on the PR branch and cross-checked the actual workflow tree on origin/master. Greptile's three findings all reproduce. Adding the concrete remediation and one extra docs inaccuracy below.

1. Coverage gate breaks every matrix job (confirmed) — and here's why per-shard fails

tests.yml:110 runs each job with both a shard and a whole-tree coverage gate:

run: pytest tests/ -v --timeout=60 --shard-id=${{ matrix.shard }} --num-shards=3 --cov=. --cov-report=xml --cov-fail-under=80

The matrix is python-version: ['3.11','3.12','3.13'] × shard: [0,1,2] (tests.yml:68,76), so each job runs only ~1/3 of the suite but measures coverage against the whole tree (--cov=.). Each shard will report roughly a third of real coverage and trip --cov-fail-under=80 immediately — all 9 jobs red on the next push.

Two ways to fix it:

• Combine, don't gate per shard. Drop --cov-fail-under from the matrix, upload each shard's coverage.xml as an artifact, then add a separate coverage job that depends on the matrix, downloads all 9, runs coverage combine + coverage report --fail-under=80 once. That's the only way an 80% number is meaningful across a sharded suite.
• Or measure coverage in a single non-sharded job. Add one job that runs pytest tests/ --cov=. --cov-fail-under=80 without --shard-id, and leave the existing 9 matrix jobs as pure pass/fail. Simpler, slower.

Either keeps the speed benefit of sharding for pass/fail while making the coverage gate correct.

2. Trivy @master pin + scan-after-push (confirmed)

release.yml:61,71 use aquasecurity/trivy-action@master, executing whatever's on that third-party branch with this job's contents: write / packages: write. Pin to an immutable commit SHA. And the image scan at L60-68 runs after build-push-action (L47) has already pushed to GHCR, so a CRITICAL-CVE image is public before exit-code: 1 fires. Build locally with push: false, scan, then push on pass — or scan in a gate job that blocks the push step. (steps.meta.outputs.version itself is fine — id: meta is defined at L38.)

3. CONTRIBUTING table is wrong in both directions

Greptile caught the 4 phantom files. Checking origin/master:.github/workflows/, the actual set is:

browser-smoke.yml  docker-smoke.yml  native-windows-startup.yml  release.yml  tests.yml

So the new table (CONTRIBUTING.md:209-217) references four files that don't exist — dep-audit.yml, security-scan.yml, lint-configs.yml, feature-checks.yml — and omits two that do: docker-smoke.yml and native-windows-startup.yml. As written it documents a branch-protection policy the repo can't enforce, which is worse than no table. Either add the four workflows in this PR (then the lint/test/browser-smoke rows are accurate) or rewrite the table to match the five workflows that actually exist today.

Recommendation

The Trivy scan and a coverage gate are both worth having, but as-is this turns the matrix red and ships a misleading policy doc. Splitting it would help review: (a) coverage as a combine-job, (b) Trivy pinned-SHA + pre-push gate, (c) docs that match reality. Happy to re-review once the coverage gate is restructured.

[nesquena-hermes]

Thanks for thinking about CI hardening — Trivy image scanning is a welcome direction. But this PR can't merge as-is: it would brick the release pipeline and the docs describe checks that don't exist. Specifics:

1. The 80% coverage gate would fail every PR and every release tag (blocking).
--cov-fail-under=80 is appended to the per-shard test command, but each shard runs only 1/3 of the suite (--num-shards=3). Coverage is measured per-shard, so each shard sees roughly a third of the codebase exercised → it will report well under 80% and fail, on every PR and every v* tag. To enforce a real total-coverage threshold you'd have to collect coverage data per shard (e.g. --cov-report= to emit .coverage.<shard>), upload the fragments as artifacts, and run a separate coverage combine + coverage report --fail-under=80 job after all shards finish. A per-shard --cov-fail-under can't express a whole-suite threshold.

Separately, please treat the value of a hard 80% gate as an open question for the maintainer rather than something to wire in by default — measure current total coverage first; an advisory (non-blocking) report is the safer first step.

2. release.yml Trivy step blocks every release on any base-image CVE (blocking).
exit-code: '1' with severity: 'CRITICAL,HIGH' on the image scan means a single new HIGH CVE in an upstream base-image layer (which you don't control and which appears constantly) fails the tagged release build and stops the Docker push. For a scanner you don't gate merges on yet, run it non-blocking first (exit-code: '0', upload the report) so you can see signal without wedging releases. The filesystem/misconfig scan you already set to exit-code: '0' — match that for the image scan.

3. The CONTRIBUTING.md branch-protection table lists workflows that don't exist.
It references dep-audit.yml, security-scan.yml, lint-configs.yml, and feature-checks.yml — none of those exist in .github/workflows/ (only browser-smoke.yml, docker-smoke.yml, native-windows-startup.yml, release.yml, tests.yml are present). Documenting required status checks that don't exist will mislead contributors and can't be enforced. Please document only the checks that actually run.

Suggested path forward: split this into (a) the Trivy scans, non-blocking to start, and (b) a CONTRIBUTING note that matches the real workflow set — and drop the hard coverage gate (or make it an advisory combined-coverage report) until there's a maintainer decision on the threshold. Happy to re-review once it's scoped down.