README Guardrails
Validate README files against documentation standards. Ensure repositories have proper documentation by checking for file existence, minimum content length, and required section headings.
readme to your lunar-config.yml:uses: github://earthly/lunar-lib/policies/readme@v1.0.0
Included Guardrails
This policy includes 3 guardrails that enforce standards for your repository and ownership.
readme-exists
Verifies that a README.md or README file exists in the repository root.
Every repository should have basic documentation for discoverability.
readme-min-line-count
Requires the README to have a minimum number of lines (default 25). Prevents placeholder READMEs that lack useful information.
readme-required-sections
Ensures the README contains required section headings (e.g., Installation, Usage). Configurable via the required_sections input parameter.
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_lines
|
Optional |
25
|
Minimum number of lines required in README file |
required_sections
|
Required | — | Comma-separated list of required sections in README file |
Documentation
View on GitHubREADME Guardrails
Enforces README best practices including file existence, minimum content length, and required sections.
Overview
This policy plugin validates README files against common documentation standards. It ensures repositories have proper documentation by checking for file existence, minimum content length, and required section headings. These policies help maintain consistent documentation quality across your organization.
Policies
This plugin provides the following policies (use include to select a subset):
| Policy | Description | Failure Meaning |
|---|---|---|
readme-exists |
Ensures README file exists in the repository root | README file not found |
readme-min-line-count |
Ensures README file meets minimum line count | README file has fewer lines than required |
readme-required-sections |
Ensures README file contains required section headings | README file is missing one or more required sections |
Required Data
This policy reads from the following Component JSON paths:
| Path | Type | Provided By |
|---|---|---|
.repo.readme.exists |
boolean | readme collector |
.repo.readme.lines |
number | readme collector |
.repo.readme.sections[] |
array | readme collector |
Note: Ensure the corresponding collector is configured before enabling this policy.
Installation
Add to your lunar-config.yml:
policies:
- uses: github://earthly/lunar-lib/policies/readme@v1.0.0
on: ["domain:your-domain"] # Or use tags like [backend, kubernetes]
enforcement: report-pr # Options: draft, score, report-pr, block-pr, block-release, block-pr-and-release
# include: [readme-exists] # Only run specific checks (omit to run all)
# with: # Uncomment if inputs are needed
# min_lines: 50
# required_sections: "Installation,Usage,Contributing"
Examples
Passing Example
{
"repo": {
"readme": {
"exists": true,
"path": "README.md",
"lines": 150,
"sections": [
"Installation",
"Usage",
"API",
"Contributing",
"License"
]
}
}
}
This example passes all three policies when configured with:
min_lines: "50"required_sections: "Installation,Usage,Contributing"
Failing Examples
README file doesn't exist (fails readme-exists)
{
"repo": {
"readme": {
"exists": false
}
}
}
Failure message: "README file not found (expected README.md or README)"
README file has too few lines (fails readme-min-line-count)
{
"repo": {
"readme": {
"exists": true,
"path": "README.md",
"lines": 25,
"sections": ["Installation", "Usage"]
}
}
}
Failure message: "README file has 25 lines, but minimum required is 50"
README file missing required sections (fails readme-required-sections)
{
"repo": {
"readme": {
"exists": true,
"path": "README.md",
"lines": 150,
"sections": [
"Installation",
"Usage"
]
}
}
}
Failure message: "README file is missing required sections: Contributing"
Remediation
readme-exists
Create a README file (README.md or README) in the repository root:
# Project Name
Description of your project.
## Installation
...
## Usage
...
readme-min-line-count
Add more content to your README file to meet the minimum line count requirement. Consider adding:
- Detailed installation instructions
- Usage examples
- Configuration options
- API documentation
- Contributing guidelines
- License information
readme-required-sections
Add the missing required section headings to your README file. Section headings should use markdown header syntax (#, ##, ###, etc.). For example:
# Project Name
## Installation
...
## Usage
...
## Contributing
...
Section matching is case-insensitive, so "Installation", "installation", and "INSTALLATION" all match the required section "Installation".
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 engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.
Infrastructure conventions
Post-mortem action items
Security & compliance policies
Testing & quality requirements