Code Quality Guardrails
Enforce code-quality standards. Verifies a code-quality scanner ran, the tool's pass/fail signal is green, and coverage, duplication, and severity-bucketed issue counts meet configurable thresholds. Reads the normalized `.code_quality` path populated by the `sonarqube` collector.
code-quality to your lunar-config.yml:uses: github://earthly/lunar-lib/policies/code-quality@v1.0.5
Included Guardrails
This policy includes 6 guardrails that enforce standards for your testing and quality.
executed
Verifies that a code-quality scanner was executed on the component.
Fails if no scanner has written to .code_quality.
passing
Verifies the scanner's overall pass/fail signal is green. Reads the
tool-agnostic .code_quality.passing field, derived from the scanner's
own quality gate outcome.
min-coverage
Ensures line-coverage percentage meets a configurable minimum. Reads
.code_quality.coverage_percentage. Fails if the field is missing.
max-duplication
Ensures duplicated-lines percentage stays under a configurable maximum.
Reads .code_quality.duplication_percentage.
max-severity
Ensures no code-quality issues at or above the configured severity
threshold. Configure min_severity to set the threshold (critical,
high, medium, low).
max-total
Ensures total code-quality issues are under a configurable threshold.
How Guardrails Fit into Lunar
Lunar guardrails define your engineering standards as code. They evaluate data collected by integrations and produce pass/fail checks with actionable feedback.
Policies support gradual enforcement—from silent scoring to blocking PRs or deployments—letting you roll out standards at your own pace without disrupting existing workflows.
Learn How Lunar Works →Required Integrations
This policy evaluates data gathered by one or more of the following integration(s).
Make sure to enable them in your lunar-config.yml.
Configuration
Configure this policy in your lunar-config.yml.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
min_severity
|
Optional |
high
|
Minimum severity to fail on (critical, high, medium, low) |
max_total_threshold
|
Required | — | Maximum total issues allowed (must be configured) |
min_coverage_percentage
|
Optional |
80
|
Minimum line-coverage percentage (0-100) |
max_duplication_percentage
|
Optional |
5
|
Maximum duplicated-lines percentage (0-100) |
Documentation
View on GitHubCode Quality Guardrails
Enforce code-quality standards across any scanner that writes to .code_quality.
Overview
Validates that a code-quality scanner ran, the tool's overall pass/fail signal is green, and that coverage, duplication, and severity-bucketed issue counts meet configurable thresholds. Reads the tool-agnostic .code_quality Component JSON path, which is populated by code quality collectors such as sonarqube. Apply broadly as a "code quality happens" guardrail, or bring-your-own thresholds per domain.
Policies
This plugin provides the following policies (use include to select a subset):
| Policy | Description | Failure Meaning |
|---|---|---|
executed |
Verifies a code-quality scanner ran | No scanner has written to .code_quality |
passing |
Tool's pass/fail signal is green | .code_quality.passing is false (quality gate failed) |
min-coverage |
Line-coverage meets minimum | Coverage below configured threshold or missing |
max-duplication |
Duplicated-lines under threshold | Duplication above configured threshold |
max-severity |
No issues at or above severity threshold | Issues found at configured severity or higher |
max-total |
Total issues under threshold | Total issue count exceeds configured limit |
Required Data
This policy reads from the following Component JSON paths:
| Path | Type | Provided By |
|---|---|---|
.code_quality |
object | sonarqube collector |
.code_quality.passing |
bool | sonarqube collector (derived from the tool's quality gate) |
.code_quality.coverage_percentage |
number | sonarqube collector |
.code_quality.duplication_percentage |
number | sonarqube collector |
.code_quality.issues.total |
number | sonarqube collector |
.code_quality.issues.critical |
number | sonarqube collector |
.code_quality.issues.high |
number | sonarqube collector |
.code_quality.issues.medium |
number | sonarqube collector |
.code_quality.issues.low |
number | sonarqube collector |
Installation
Add to your lunar-config.yml:
policies:
- uses: github://earthly/lunar-lib/policies/code-quality@v1.0.0
on: ["domain:your-domain"]
enforcement: report-pr
# include: [executed, passing] # Only run specific checks
with:
min_severity: "high" # Fail on critical and high issues
max_total_threshold: "50" # Fail if more than 50 total issues
min_coverage_percentage: "80" # Fail under 80% line coverage
max_duplication_percentage: "5" # Fail above 5% duplicated lines
Examples
Passing Example
{
"code_quality": {
"source": { "tool": "sonarqube", "integration": "api" },
"passing": true,
"coverage_percentage": 82.5,
"duplication_percentage": 3.1,
"issues": { "total": 12, "critical": 0, "high": 0, "medium": 2, "low": 10 }
}
}
Failing Example
{
"code_quality": {
"source": { "tool": "sonarqube", "integration": "api" },
"passing": false,
"coverage_percentage": 61.4,
"duplication_percentage": 8.2,
"issues": { "total": 120, "critical": 2, "high": 5, "medium": 30, "low": 83 }
}
}
Failure messages:
executed: "No code-quality scanning data found. Ensure thesonarqubecollector is configured."passing: "Code-quality gate failed (.code_quality.passing is false)"min-coverage: "Line coverage 61.4% is below minimum 80%"max-duplication: "Duplication 8.2% exceeds maximum 5%"max-severity: "Critical code-quality issues detected (2 found)"max-total: "Total code-quality issues (120) exceeds threshold (50)"
Remediation
When this policy fails, you can resolve it by:
executedfailure: Configure thesonarqubecollector — either by runningsonar-scannerin CI (soapican read the results) or by lettingautorun it.passingfailure: Fix the specific quality-gate conditions flagged by the scanner.min-coveragefailure: Add tests or configure coverage reporting for uncovered code paths.max-duplicationfailure: Refactor duplicated blocks into shared helpers.max-severityfailure: Address issues at or above the configured severity in the scanner UI.max-totalfailure: Reduce overall issue count by fixing or acknowledging flagged items.
Open Source
This policy is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore how individual guardrails work with specific integrations.
Ready to Automate Your Standards?
See how Lunar can turn your AGENTS.md, engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 200+ built-in guardrails.
AI agent rules & prompt files
Post-mortem action items
Security & compliance policies
Testing & quality requirements