{"id":50216277,"url":"https://github.com/rogerchappel/runbooklint","last_synced_at":"2026-05-26T09:04:26.595Z","repository":{"id":358550390,"uuid":"1240530253","full_name":"rogerchappel/runbooklint","owner":"rogerchappel","description":"Local-first Markdown runbook linter for safer operational procedures","archived":false,"fork":false,"pushed_at":"2026-05-25T20:06:47.000Z","size":56,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T22:10:41.099Z","etag":null,"topics":["cli","devops","incident-response","lint","markdown","runbook","sre"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rogerchappel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-16T08:41:57.000Z","updated_at":"2026-05-25T20:06:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rogerchappel/runbooklint","commit_stats":null,"previous_names":["rogerchappel/runbooklint"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rogerchappel/runbooklint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Frunbooklint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Frunbooklint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Frunbooklint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Frunbooklint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rogerchappel","download_url":"https://codeload.github.com/rogerchappel/runbooklint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Frunbooklint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33512343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","devops","incident-response","lint","markdown","runbook","sre"],"created_at":"2026-05-26T09:04:10.263Z","updated_at":"2026-05-26T09:04:26.581Z","avatar_url":"https://github.com/rogerchappel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RunbookLint\n\nRunbookLint is a local-first Markdown linter for operational runbooks. It turns release, incident, support, and agent handoff docs into checkable procedures by flagging missing safety sections, risky commands, undefined placeholders, and vague operational language.\n\nIt never executes commands and never calls hosted APIs.\n\n## Quick start\n\n```sh\nnpm install\nnpm run build\nnode dist/cli.js check fixtures/clean-release.md\n```\n\nInitialize a project policy:\n\n```sh\nnode dist/cli.js init --preset oss-release\n```\n\nCheck a directory and fail CI on warnings or errors:\n\n```sh\nnode dist/cli.js check docs --format json --fail-on warning\n```\n\n## CLI\n\n```sh\nrunbooklint check [paths...] [--format markdown|json] [--fail-on info|warning|error] [--output file] [--policy file]\nrunbooklint init [--preset oss-release|incident|agent-handoff] [--print] [--force]\n```\n\n### Reports\n\nMarkdown is the default report format. JSON is stable and deterministic for automation.\n\n```sh\nnode dist/cli.js check fixtures --format markdown --output reports/runbooklint.md\nnode dist/cli.js check fixtures --format json --output reports/runbooklint.json\n```\n\n## What it checks\n\n- Required sections such as purpose, scope, prerequisites, procedure, validation, and rollback.\n- Owner or handoff contacts.\n- Environment scope.\n- Shell code fences containing dangerous patterns such as `rm -rf`, `sudo`, `curl | bash`, force pushes, and production-impacting commands.\n- TODO/TBD/FIXME placeholders.\n- Undefined `{{VARIABLE}}` and `${VARIABLE}` placeholders.\n- Banned vague phrases configured by policy.\n\n## Policy configuration\n\nRunbookLint loads `.runbooklint.json` from the current directory unless `--policy` is supplied. See [docs/POLICY.md](docs/POLICY.md) for the full policy reference.\n\n```json\n{\n  \"requiredHeadings\": [\"purpose\", \"scope\", \"prerequisites\", \"procedure\", \"validation\", \"rollback\"],\n  \"ownerHeadings\": [\"owner\", \"contacts\"],\n  \"environmentHeadings\": [\"scope\", \"environment\"],\n  \"requiredVariableDefinitions\": [\"OWNER\", \"TARGET_ENV\"],\n  \"allowMissingOwner\": false\n}\n```\n\nGenerate preset policies with:\n\n```sh\nnode dist/cli.js init --preset oss-release --print\nnode dist/cli.js init --preset incident --print\nnode dist/cli.js init --preset agent-handoff --print\n```\n\n## CI usage\n\n```yaml\n- run: npm ci\n- run: npm test\n- run: npm run check\n- run: npm run build\n- run: node dist/cli.js check docs --fail-on warning\n```\n\n## Safety model\n\nRunbookLint is conservative. It parses Markdown and reports likely issues; it does not execute runbook commands, mutate infrastructure, evaluate shell expansions, or contact external services. Treat findings as review prompts, not a replacement for human operational judgment.\n\n## Limitations\n\n- Markdown parsing is intentionally lightweight and optimized for runbooks, not every CommonMark edge case.\n- Risk rules are pattern-based and can produce false positives or false negatives.\n- `.gitignore` support covers common deterministic path ignores, not every advanced gitignore feature.\n- Inline suppressions and SARIF output are planned but not yet implemented.\n\n## Development\n\n```sh\nnpm install\nnpm test\nnpm run check\nnpm run build\nnpm run smoke\nbash scripts/validate.sh\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Security\n\nSee [SECURITY.md](SECURITY.md). Please do not include secrets or private incident data in bug reports.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frogerchappel%2Frunbooklint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frogerchappel%2Frunbooklint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frogerchappel%2Frunbooklint/lists"}