CI Guardrails
Enforces lint quality and supply-chain hygiene for CI configurations. Checks that CI config files pass lint validation and that third-party CI dependencies (actions, orbs, templates) use pinned versions.
ci to your lunar-config.yml:uses: github://earthly/lunar-lib/policies/ci@v1.0.5
Included Guardrails
This policy includes 3 guardrails that enforce standards for your devex build and ci.
lint-clean
Ensures no lint errors across CI configuration files. Reads from the normalized .ci.lint path — works with any CI vendor's lint tool (actionlint for GHA, gitlab-ci-lint for GitLab, etc.).
dependencies-pinned
Verifies all third-party CI dependencies use SHA or tag pins, not branch refs. Reads from the normalized .ci.dependencies path — works with GHA actions, GitLab templates, CircleCI orbs, etc.
no-mutable-refs
Ensures no third-party CI dependencies reference mutable refs like @main, @master, or @latest. Reads from normalized .ci.dependencies.
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.
Documentation
View on GitHubCI Guardrails
Enforces CI configuration lint quality and supply-chain dependency pinning.
Overview
This policy validates that CI configurations are well-formed and that third-party CI dependencies follow supply-chain best practices. It reads from normalized Component JSON paths (.ci.lint, .ci.dependencies), so it works regardless of which CI vendor collector populated the data — GitHub Actions, GitLab CI, CircleCI, etc.
Policies
This plugin provides the following policies (use include to select a subset):
| Policy | Description |
|---|---|
lint-clean |
No lint errors across CI configuration files |
dependencies-pinned |
All 3rd-party CI dependencies use SHA or tag pins (not branch refs) |
no-mutable-refs |
No 3rd-party CI dependencies reference mutable refs (@main, @master, @latest) |
Required Data
This policy reads from normalized (vendor-agnostic) Component JSON paths only:
| Path | Type | Provided By |
|---|---|---|
.ci.lint |
object | Any CI collector (e.g. github-actions) |
.ci.dependencies |
object | Any CI collector (e.g. github-actions) |
Note: At least one CI collector must be configured to populate these normalized paths.
Installation
Add to your lunar-config.yml:
policies:
- uses: github://earthly/lunar-lib/policies/ci@main
on: ["domain:your-domain"]
enforcement: report-pr
# include: [lint-clean, dependencies-pinned] # Only run specific checks
Examples
Passing Example
{
"ci": {
"lint": {
"errors": [],
"error_count": 0,
"warning_count": 0
},
"dependencies": {
"total": 2,
"pinned": 2,
"unpinned": 0,
"items": [
{ "name": "actions/checkout", "ref": "abc123def456", "pinning": "sha", "party": "1st" },
{ "name": "docker/build-push-action", "ref": "v5.1.0", "pinning": "tag", "party": "3rd" }
],
"third_party_unpinned": []
}
}
}
Failing Example
{
"ci": {
"lint": {
"errors": [{ "file": ".github/workflows/ci.yml", "line": 42, "message": "unknown field", "rule": "syntax-check" }],
"error_count": 1,
"warning_count": 0
},
"dependencies": {
"total": 1,
"pinned": 0,
"unpinned": 1,
"items": [
{ "name": "docker/build-push-action", "ref": "main", "pinning": "branch", "party": "3rd" }
],
"third_party_unpinned": ["docker/build-push-action@main"]
}
}
}
Failure messages:
lint-clean: "1 lint error(s) found across CI configuration files"dependencies-pinned: "1 third-party CI dependency(ies) not pinned to SHA or tag: docker/build-push-action@main"no-mutable-refs: "1 third-party CI dependency(ies) using mutable refs: docker/build-push-action@main"
Remediation
When this policy fails, you can resolve it by:
lint-cleanfailure: Fix the reported lint errors. Run your CI vendor's linter locally (e.g.actionlintfor GHA,gitlab-ci-lintfor GitLab) to see all issues with file and line references.dependencies-pinnedfailure: Pin third-party CI dependencies to a SHA (@abc123...) or a specific tag (@v4.1.0) instead of using branch refs.no-mutable-refsfailure: Replace mutable refs like@main,@master, or@latestwith immutable SHA or tag references.
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