🛡️ Cerber Core — CI Contract Guard for GitHub Actions

Detects workflow/config drift across repos and enforces a single source of truth via CERBER.md.

AI doesn't break your project. Lack of a contract does.

What is Cerber Core?

Cerber enforces your project roadmap as executable contract (CERBER.md). Write rules once, get automatic validation on every commit + CI run.

What Cerber Is (and Isn't)

✅ Contract guard — Validates your CERBER.md rules are enforced
✅ Drift detector — Catches when CI config/workflow changes break protection
✅ Works WITH existing tools — Doesn't replace ESLint/Prettier/tests. Ensures they stay required.

❌ Not a linter — Use ESLint for code style
❌ Not a test runner — Use Jest/Vitest for unit tests
❌ Not a deployment tool — Use your existing CD pipeline

Think of it as: Policy-as-code layer that prevents your other tools from being bypassed.

Why? (The CI Drift Problem)

• ✅ AI agents follow your roadmap → Agent pastes code matching CERBER.md
• ❌ Human bypasses rules → Commit sneaks through, CI green but wrong
• ❌ CI config drifts → Workflow changes, gates disappear, protection gone

Solution: Guardian blocks bad commits before they reach CI. CI re-validates and protects itself from tampering.

🏆 Proof: Used in Production

Cerber protects real SaaS applications. See it in action:

Eliksir Platform CI Pipelines:

• 🎨 Frontend: Guardian Schema Check + tests ✅
• ⚙️ Backend: Quality Gate + deploy checks ✅

These aren't demo projects - live production systems serving real users, protected by Cerber since day one.

📖 Full case study: How Cerber prevented 47 production bugs

💬 Community (Discord)

Join the Cerber Core Discord for support, feedback, and CI/Doctor showcases: 👉 https://discord.gg/V8G5qw5D

• Questions: ask in #general
• Feedback / bugs: #feedback (bugs can also go to GitHub Issues)
• Proofs: post your CI runs / doctor output in #showcase

🚀 Quick Start (60 seconds)

# 1. Install
npm i -D cerber-core

# 2. Generate contract template
npx cerber init

# 3. Edit CERBER.md (use AI assistant or manual)
# → Define your roadmap, tech stack, protected assets

# 4. Generate hooks + CI workflow
npx cerber init

# 5. Verify setup
npx cerber doctor

# 6. Commit and push
git add .
git commit -m "feat: add Cerber protection"
git push

That's it. Guardian now blocks bad commits. CI re-validates and protects itself.

What Cerber Checks

Pre-commit (Guardian)

• ❌ Secrets in code (API keys, tokens)
• ❌ Forbidden patterns (eval, console.log in prod)
• ❌ Missing required imports
• ❌ Protected file deletions
• ✅ Schema validation (if enabled)

CI (GitHub Actions)

• ❌ Workflow tampering (job ID changes)
• ❌ Missing required checks
• ❌ Contract violations
• ✅ Re-runs Guardian validation

📍 TODAY: CI contract guard + workflow drift detection
🚀 ROADMAP: Post-deploy health gates (experimental in v1.1, production-ready in v2.0)

Doctor Command

• ❌ Missing CERBER.md
• ❌ Missing schema (strict mode)
• ❌ Missing pre-commit hook
• ❌ Missing CI workflow
• ✅ Override state validation

⚖️ Stability Policy

Cerber is a devtool — we don't break pipelines:

• CLI flags + exit codes: Follow SemVer. Breaking changes = major version bump.
• JSON output: Versioned schema (e.g., {"version": "1.0", ...}). New fields = minor, changed fields = major.
• CI workflow templates: Generated files are yours to customize. Updates = opt-in via cerber init --force.

Current stability: v1.1.11 is production-ready for CI contract guard use case. See production proof.

Example: CI Drift Detected

$ npx cerber doctor

[Cerber Doctor] Setup Validation

[OK] All checks passed!

Configuration:
  Mode: dev
  Guardian: enabled
  Health: enabled
  CI: github
  Override: DISABLED

[READY] Ready to commit!

⭐ If Cerber helped you, star the repo: https://github.com/Agaslez/cerber-core
💬 Join Discord for feedback/support: https://discord.gg/V8G5qw5D

When drift detected:

$ npx cerber doctor

[Cerber Doctor] Setup Validation

[FAIL] Issues found:

[!] .github/workflows/cerber.yml
    GitHub workflow not found

Next Steps:

1. Re-run initialization to generate missing files:
   npx cerber init

Help: https://github.com/Agaslez/cerber-core/discussions

How to Use Cerber (Full Workflow)

Cerber is simple: write rules once in CERBER.md, enforce on every commit + CI run.

📍 TODAY: Pre-commit Guardian + CI workflow drift detection
🚀 ROADMAP: Post-deploy health gates (experimental)

Roadmap → CERBER.md contract → enforced automatically on every commit/push.

1) Install

npm i -D cerber-core

2) Generate CERBER.md

npx cerber init

If CERBER.md did not exist, Cerber creates a template and stops.
Now YOU fill the contract (ideally with an AI assistant).

3) Teach Cerber using your roadmap (fastest way)

Take your project roadmap + repo structure and paste it into ChatGPT/Claude/Cursor with the Cerber Contract Translator prompt (see below).

Then:

• Paste the generated contract into CERBER.md
• Run init again to generate hooks/workflows/templates:

  npx cerber init

4) Verify everything (Doctor)

npx cerber doctor

Exit codes:

• 0 ✅ All checks pass
• 2 ❌ Missing CERBER.md
• 3 ❌ Missing schema (strict mode)
• 4 ❌ Missing hook/workflow

5) Commit and push (Guardian + CI)

• git commit → Guardian validates staged changes (blocks violations)
• git push → GitHub Actions validates again in CI

💬 Feedback & Support

Having issues? Want to share your setup?

• 💬 Discord: https://discord.gg/V8G5qw5D (fastest support)
• 🐛 GitHub Issues: Report bugs
• 💡 GitHub Discussions: Ask questions, share ideas
• 📖 Case Studies: See Cerber in production

Show your CI runs in Discord #showcase!

Cerber Contract Translator (Copy/Paste Prompt)

Use this to generate a production-ready CERBER.md from your roadmap.
Cerber does NOT design your architecture. It enforces what you write.

PROMPT:

You are a "Cerber Contract Translator". Convert my roadmap + repo structure into a `CERBER.md` contract.

RULES:
- Do NOT invent architecture or rules.
- Only translate what I explicitly provide.
- If something is missing, ask up to 10 questions in a `QUESTIONS` section and leave placeholders.
- Output must be a complete `CERBER.md` with:
  1) CERBER_CONTRACT (YAML)
  2) ROADMAP_AS_LAW (milestones)
  3) AI_AGENT_RULES (no guessing)
  4) PROTECTED_ASSETS
  5) CERBER_OVERRIDE (TTL safety fuse)
  6) QUESTIONS

INPUT I PROVIDE:
- Roadmap (what we are building, milestones, priorities)
- Repo structure (`tree -L 3` or folder list)
- Tech stack + commands for smoke/e2e/build
- Integrations (Stripe/Ghost/Cloudinary/etc.)
- What files/paths are "protected" from deletion

Now generate `CERBER.md`.

For AI Agents (Copilot / Cursor / Windsurf / Claude / etc.)

Single rule: CERBER.md is the ONLY source of truth.

Agent must follow this protocol

1. If CERBER.md is missing:

   • Run npx cerber init to generate template
   • STOP (user must provide contract content)

2. If CERBER.md exists:

   • Read it first
   • Execute exactly what it says
   • Do NOT invent rules, do NOT infer architecture

3. Schema policy (important):

   • If schema.mode: strict → DO NOT generate schema files
   • If schema.mode: template_only → you may generate only the minimal template (NOT decisions)

4. Safety rules:

   • Never disable or rename CI job id: cerber-ci
   • Never remove: CERBER.md, .github/workflows/cerber.yml, scripts/cerber-guardian.mjs, .husky/pre-commit, .github/CODEOWNERS
   • Never bypass checks using continue-on-error
   • Never use cat <<EOF for TS/JS (corrupts ${} template literals)

If a required rule is not present in CERBER.md → ASK USER or FAIL FAST.

🔗 Links

• Repository: https://github.com/Agaslez/cerber-core
• Releases: https://github.com/Agaslez/cerber-core/releases
• Security Policy: https://github.com/Agaslez/cerber-core/blob/main/SECURITY.md
• Discussions: https://github.com/Agaslez/cerber-core/discussions
• Full Documentation: docs/README_LONG.md

📋 Minimal CERBER.md Example

## CERBER_CONTRACT
\```yaml
version: 1
mode: solo  # solo | dev | team

guardian:
  enabled: true
  schemaFile: BACKEND_SCHEMA.mjs

schema:
  enabled: true
  file: BACKEND_SCHEMA.mjs
  mode: strict  # Recommended: You create schema, Cerber never generates

health:
  enabled: true
  endpoint: /api/health

ci:
  provider: github
  branches: [main]
\```

Schema modes:

• strict (recommended) → You design architecture, Cerber guards it
• template_only → Helper scaffold for beginners (NOT design decisions)

📚 Documentation

Quick Links:

• 📖 Full Documentation (Long README)
• 🛡️ Guardian API - Pre-commit validation
• 🔍 Cerber API - Runtime health checks
• ⚡ SOLO Layer - Automation for solo developers (666 LOC)
• 👥 TEAM Layer - Focus Mode + module system (1861 LOC)
• 🏗️ Architecture - System design philosophy
• 🔐 Security Policy - Supply-chain security, vulnerability reporting
• 🤝 Contributing - How to contribute

Workflows by Team Size:

• Solo Developer - 1 person, 15min setup
• Small Team (2-5) - Module system, 1-2h setup
• Growing Team (5-20) - Architecture governance

Examples:

• Frontend Schema (React)
• Backend Schema (Express)
• Health Checks
• SOLO Integration
• TEAM Integration

✨ Key Features

Guardian 1.0 (Pre-commit)

• Schema-as-Code (architecture rules in version control)
• Fast feedback (<1s validation vs 5min CI wait)
• Required imports + forbidden patterns
• Architect approvals (traceable exceptions)

Cerber 2.1 (Runtime)

• Detailed diagnostics (diagnosis + rootCause + fix)
• Severity levels (critical/error/warning)
• Component-based health checks
• Performance tracking

SOLO Layer

• Auto-repair (format, deps, changelog)
• Performance budget enforcement
• Daily dashboard
• Dependency health checks

TEAM Layer

• Focus Mode (500 LOC context vs 10K LOC for AI) ⭐
• Module boundaries enforcement
• Connection contracts between modules
• CERBER.md project mapping

🚨 Emergency Override

For P0 production hotfixes only, controlled safety fuse with strict TTL:

## CERBER_OVERRIDE
enabled: true
reason: "P0 - Payment API down, emergency rollback"
expires: "2026-01-04T18:00:00Z"  # 6-hour TTL
approvedBy: "CTO Name"

What Override DOES:

• ✅ Allows pre-commit to pass WITH WARNING (audit trail logged)
• ✅ Can skip postDeploy gate if configured

What Override NEVER DOES:

• ❌ Disable cerber-integrity job (self-protection always runs)
• ❌ Disable entire CI pipeline (build/test/lint must pass)
• ❌ Disable CODEOWNERS enforcement (team mode)

Use sparingly. After expiry, guardian proceeds with normal validation.

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

git clone https://github.com/Agaslez/cerber-core.git
cd cerber-core
npm install
npm run build
npm test

📞 Support & Links

• 💬 Discord: Join community
• 🐛 Issues: GitHub Issues
• 💡 Discussions: GitHub Discussions
• 📖 Full Docs: docs/README_LONG.md
• 📚 Case Study: How Cerber prevented 47 bugs
• 🎭 Story: The team behind Cerber
• 🔐 Security: Report vulnerabilities to st.pitek@gmail.com
• ⭐ Repository: github.com/Agaslez/cerber-core

📄 License

MIT © 2026 Stefan Pitek

Free for commercial use. See LICENSE for details.

🌟 About

Founded by Agata Ślęzak, created and maintained by Stefan Pitek

• 📖 Read the full story: docs/STORY.md

Read the full story: docs/STORY.md

Support development: docs/SPONSORING.md