Ruby Project Guardrails
Enforce Ruby-specific project standards including Gemfile presence, lockfile management, Ruby version pinning, and bundler-audit vulnerability compliance.
ruby to your lunar-config.yml:uses: github://earthly/lunar-lib/policies/ruby@v1.0.5
Included Guardrails
This policy includes 8 guardrails that enforce standards for your devex build and ci.
gemfile-exists
Ensures the project has a Gemfile for dependency management. Required for all Ruby projects using Bundler.
lockfile-exists
Ensures the project has a Gemfile.lock for reproducible dependency resolution. Pinned dependencies prevent unexpected version drift across environments.
ruby-version-set
Ensures the Ruby version is explicitly specified via a .ruby-version file or a ruby directive in the Gemfile. Pinning the Ruby version prevents environment inconsistencies between development, CI, and production.
bundler-audit-clean
Ensures bundler-audit reports no known vulnerabilities in the project's gem dependencies. Skips gracefully if bundler-audit has not been run. Requires the bundler-audit-cicd collector to capture audit results from CI.
min-ruby-version
Ensures the project uses at least the minimum required Ruby version. Helps maintain security and compatibility standards.
min-ruby-version-cicd
Ensures the Ruby version used in CI/CD commands meets the minimum required version for build environments.
min-bundler-version-cicd
Ensures the Bundler version used in CI/CD commands meets the minimum required version. Outdated Bundler versions may have security issues or lack features needed for reliable dependency resolution.
min-rake-version-cicd
Ensures the Rake version used in CI/CD commands meets the minimum required version for build automation.
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 |
|---|---|---|---|
max_audit_vulnerabilities
|
Optional |
0
|
Maximum allowed known vulnerabilities from bundler-audit (0 = must be clean) |
min_ruby_version
|
Optional |
3.0
|
Minimum required Ruby version (e.g., "3.0", "3.2") |
min_ruby_version_cicd
|
Optional |
3.0
|
Minimum required Ruby version for CI/CD commands |
min_bundler_version_cicd
|
Optional |
2.4
|
Minimum required Bundler version for CI/CD commands |
min_rake_version_cicd
|
Optional |
13.0
|
Minimum required Rake version for CI/CD commands |
Documentation
View on GitHubRuby Project Guardrails
Enforces Ruby project structure, dependency management, and security standards.
Overview
This policy enforces Ruby-specific engineering standards including Gemfile presence, lockfile management for reproducible builds, Ruby version pinning, and vulnerability-free dependencies via bundler-audit. It applies to any component with Ruby project indicators and skips gracefully when no Ruby project is detected.
Policies
This plugin provides the following policies (use include to select a subset):
| Policy | Description |
|---|---|
gemfile-exists |
Ensures a Gemfile is present for dependency management |
lockfile-exists |
Ensures Gemfile.lock exists for reproducible dependency resolution |
ruby-version-set |
Ensures Ruby version is pinned via .ruby-version or Gemfile ruby directive |
bundler-audit-clean |
Ensures no known vulnerabilities in gem dependencies (skips if no audit data) |
min-ruby-version |
Ensures project Ruby version meets the configured minimum |
min-ruby-version-cicd |
Ensures Ruby version used in CI/CD meets the configured minimum |
min-bundler-version-cicd |
Ensures Bundler version used in CI/CD meets the configured minimum |
min-rake-version-cicd |
Ensures Rake version used in CI/CD meets the configured minimum |
Required Data
This policy reads from the following Component JSON paths:
| Path | Type | Provided By |
|---|---|---|
.lang.ruby |
object | ruby collector |
.lang.ruby.gemfile_exists |
boolean | ruby collector (project) |
.lang.ruby.gemfile_lock_exists |
boolean | ruby collector (project) |
.lang.ruby.ruby_version_file_exists |
boolean | ruby collector (project) |
.lang.ruby.version |
string | ruby collector (project) |
.lang.ruby.bundler_audit.vulnerabilities |
array | ruby collector (bundler-audit or bundler-audit-cicd) |
.lang.ruby.cicd.cmds |
array | ruby collector (cicd) |
.lang.ruby.bundler.cicd.cmds |
array | ruby collector (bundler-cicd) |
.lang.ruby.rake.cicd.cmds |
array | ruby collector (rake-cicd) |
Note: Ensure the ruby collector is configured before enabling this policy.
Installation
Add to your lunar-config.yml:
policies:
- uses: github://earthly/lunar-lib/policies/ruby@main
on: ["domain:your-domain"]
enforcement: report-pr
# include: [gemfile-exists, lockfile-exists] # Only run specific checks
# with:
# max_audit_vulnerabilities: "0"
# min_ruby_version: "3.0"
# min_ruby_version_cicd: "3.0"
# min_bundler_version_cicd: "2.4"
# min_rake_version_cicd: "13.0"
Examples
Passing Example
A well-configured Ruby project with all standards met:
{
"lang": {
"ruby": {
"version": "3.2.2",
"gemfile_exists": true,
"gemfile_lock_exists": true,
"ruby_version_file_exists": true,
"bundler_audit": {
"vulnerabilities": [],
"source": { "tool": "bundler-audit", "integration": "ci" }
}
}
}
}
Failing Example
A Ruby project missing a lockfile and with a known vulnerability:
{
"lang": {
"ruby": {
"version": "3.1.0",
"gemfile_exists": true,
"gemfile_lock_exists": false,
"ruby_version_file_exists": false,
"bundler_audit": {
"vulnerabilities": [
{
"gem": "actionpack",
"version": "7.0.4",
"advisory": "CVE-2023-22795",
"title": "ReDoS vulnerability",
"criticality": "High"
}
]
}
}
}
}
Failure messages:
lockfile-exists:"Gemfile.lock not found. Run 'bundle install' and commit the lockfile for reproducible builds."ruby-version-set:"Ruby version not specified. Create a .ruby-version file or add a ruby directive to your Gemfile."bundler-audit-clean:"bundler-audit found 1 known vulnerability. Run 'bundle audit' for details and update affected gems."
Remediation
When this policy fails, you can resolve it by:
- gemfile-exists — Initialize a Gemfile with
bundle initor create one manually - lockfile-exists — Run
bundle installto generate Gemfile.lock and commit it - ruby-version-set — Create a
.ruby-versionfile (e.g.,echo "3.2.2" > .ruby-version) or addruby "3.2.2"to your Gemfile - bundler-audit-clean — Run
bundle auditto see vulnerabilities, thenbundle update <gem>to update affected gems - min-ruby-version — Update the Ruby version in
.ruby-versionor your Gemfilerubydirective to meet the minimum - min-ruby-version-cicd — Update the Ruby installation in your CI environment to the required minimum version
- min-bundler-version-cicd — Run
gem install bundlerin CI to update to a supported Bundler version - min-rake-version-cicd — Update the
rakegem in your Gemfile to meet the minimum version
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