Repo Boilerplate Guardrails
Enforce repository boilerplate standards including README quality, CODEOWNERS validation, and presence of standard files (.gitignore, LICENSE, SECURITY.md, CONTRIBUTING.md). Consolidates readme and codeowners policies into a single plugin with additional file-existence checks.
repo-boilerplate to your lunar-config.yml:uses: github://earthly/lunar-lib/policies/repo-boilerplate@v1.0.5
Included Guardrails
This policy includes 16 guardrails that enforce standards for your repository and ownership.
readme-exists
Verifies that a 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. Skips if no sections configured.
codeowners-exists
Requires a CODEOWNERS file to be present in the repository. Checks standard locations: root, .github/, or docs/.
codeowners-valid
Validates that the CODEOWNERS file has correct syntax. Checks that all owner references use valid formats (@user, @org/team, or email).
codeowners-catchall
Requires a default catch-all rule (*) in CODEOWNERS so that every file in the repository has at least one owner.
codeowners-min-owners
Ensures each CODEOWNERS rule has a minimum number of owners for redundancy. Configurable via the min_owners_per_rule input.
codeowners-team-owners
Requires at least one team-based owner (@org/team) in the CODEOWNERS file for better ownership continuity.
codeowners-no-individuals-only
Ensures each CODEOWNERS rule includes at least one team owner, not just individual users. Stricter than codeowners-team-owners which only checks that teams exist somewhere in the file.
codeowners-no-empty-rules
Flags CODEOWNERS rules that have no owners assigned, which effectively un-assigns ownership for matching files.
codeowners-max-owners
Flags CODEOWNERS rules with too many owners. Excessive owners often means diffused responsibility. Configurable via the max_owners_per_rule input.
gitignore-exists
Verifies that a .gitignore file exists in the repository root. Prevents
accidental commits of build artifacts, dependencies, and IDE files.
Reads from .repo.gitignore.
license-exists
Verifies that a LICENSE file exists in the repository root. Checks
common variants: LICENSE, LICENSE.md, LICENSE.txt, LICENCE.
Reads from .repo.license.
security-exists
Verifies that a SECURITY.md file exists in the repository root or .github/
directory. Provides a channel for responsible vulnerability disclosure.
Reads from .repo.security.
contributing-exists
Verifies that a CONTRIBUTING.md file exists in the repository root or .github/
directory. Helps external and internal contributors understand the process.
Reads from .repo.contributing.
editorconfig-exists
Verifies that an .editorconfig file exists in the repository root. Ensures
consistent coding style across editors. Use exclude/include in lunar-config
to control whether this check runs. Reads from .repo.editorconfig.
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 |
min_owners_per_rule
|
Optional |
2
|
Minimum number of owners required per CODEOWNERS rule |
max_owners_per_rule
|
Optional |
10
|
Maximum number of owners allowed per CODEOWNERS rule |
Documentation
View on GitHubRepo Boilerplate Guardrails
Enforce repository boilerplate standards for README, CODEOWNERS, and standard configuration files.
Overview
Validates that repositories maintain documentation standards, code ownership rules, and include standard boilerplate files. Consolidates the existing readme and codeowners policies into a single plugin, adding checks for .gitignore, LICENSE, SECURITY.md, CONTRIBUTING.md, and .editorconfig.
Policies
This plugin provides the following policies (use include to select a subset):
README Checks
| Policy | Description |
|---|---|
readme-exists |
Verifies a README file exists in the repository |
readme-min-line-count |
Requires README to have minimum line count (default 25) |
readme-required-sections |
Ensures README contains required section headings |
CODEOWNERS Checks
| Policy | Description |
|---|---|
codeowners-exists |
Requires a CODEOWNERS file in the repository |
codeowners-valid |
Validates CODEOWNERS syntax (owner formats) |
codeowners-catchall |
Requires a default catch-all rule (*) |
codeowners-min-owners |
Minimum owners per rule (default 2) |
codeowners-team-owners |
Requires at least one team-based owner |
codeowners-no-individuals-only |
Each rule must include a team owner |
codeowners-no-empty-rules |
Flags rules with no owners assigned |
codeowners-max-owners |
Maximum owners per rule (default 10) |
Standard File Checks
| Policy | Description |
|---|---|
gitignore-exists |
Verifies .gitignore file exists |
license-exists |
Verifies LICENSE file exists |
security-exists |
Verifies SECURITY.md file exists |
contributing-exists |
Verifies CONTRIBUTING.md file exists |
editorconfig-exists |
Verifies .editorconfig file exists (use exclude if not wanted) |
Required Data
This policy reads from the following Component JSON paths:
| Path | Type | Provided By |
|---|---|---|
.repo.readme |
object | repo-boilerplate collector (readme subcollector) |
.repo.gitignore |
object | repo-boilerplate collector (gitignore subcollector) |
.repo.license |
object | repo-boilerplate collector (license subcollector) |
.repo.security |
object | repo-boilerplate collector (security subcollector) |
.repo.contributing |
object | repo-boilerplate collector (contributing subcollector) |
.repo.editorconfig |
object | repo-boilerplate collector (editorconfig subcollector) |
.ownership.codeowners |
object | repo-boilerplate collector (codeowners subcollector) |
Note: Ensure the repo-boilerplate collector is configured before enabling this policy.
Installation
Add to your lunar-config.yml:
policies:
- uses: github://earthly/lunar-lib/policies/repo-boilerplate@main
on: ["domain:your-domain"]
enforcement: report-pr
exclude: [editorconfig-exists]
# include: [readme-exists, codeowners-exists, gitignore-exists, license-exists]
# with:
# min_lines: "25"
# required_sections: "Installation,Usage"
# min_owners_per_rule: "2"
# max_owners_per_rule: "10"
Examples
Passing Example
{
"repo": {
"readme": {
"exists": true,
"path": "README.md",
"lines": 150,
"sections": ["Installation", "Usage", "Contributing"]
},
"gitignore": { "exists": true, "path": ".gitignore", "lines": 42, "patterns": 35 },
"license": { "exists": true, "path": "LICENSE", "spdx_id": "MIT" },
"security": { "exists": true, "path": "SECURITY.md", "lines": 28, "sections": ["Reporting a Vulnerability"] },
"contributing": { "exists": true, "path": "CONTRIBUTING.md", "lines": 55, "sections": ["Getting Started", "Pull Requests"] },
"editorconfig": { "exists": true, "path": ".editorconfig", "sections": 4 }
},
"ownership": {
"codeowners": {
"exists": true,
"valid": true,
"errors": [],
"team_owners": ["@acme/platform-team"],
"rules": [
{ "pattern": "*", "owners": ["@acme/platform-team"], "owner_count": 1 }
]
}
}
}
Failing Example
{
"repo": {
"readme": { "exists": false },
"gitignore": { "exists": false },
"license": { "exists": false },
"security": { "exists": false },
"contributing": { "exists": false },
"editorconfig": { "exists": false }
},
"ownership": {
"codeowners": { "exists": false }
}
}
Failure messages:
"README file not found""No CODEOWNERS file found"".gitignore file not found""LICENSE file not found"
Remediation
When this policy fails, resolve it by adding the missing files:
- README - Add a
README.mdwith project description, installation, and usage instructions - CODEOWNERS - Add a
CODEOWNERSfile (root,.github/, ordocs/) with ownership rules - .gitignore - Add a
.gitignoreappropriate for your language/framework - LICENSE - Add a
LICENSEfile with your project's license - SECURITY.md - Add a
SECURITY.mdwith vulnerability disclosure instructions - CONTRIBUTING.md - Add a
CONTRIBUTING.mdwith contribution guidelines
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 100+ built-in guardrails.
AI agent rules & prompt files
Post-mortem action items
Security & compliance policies
Testing & quality requirements