Tutorial: Cromus Gate & Cromus Compile — GitHub CI Setup

Cromus ships two GitHub Actions and a policy engine that give you a full governance loop in CI — score existing skills, compile SOP documents into SKILL.md, and enforce team rules before anything merges. This tutorial walks through both apps, a policy-as-code layer, and the full input/output reference.

What you get

They are designed to be used together: Compile drafts your skills, Gate reviews them — nothing machine-generated merges without a verdict. But each works independently if your team only needs one half.

Before you start

Requirements:

• Cromus plan: Builder or higher (Gate scoring is unlimited on every plan; Compile requires Builder or above)
• A GitHub repository your team uses for AI workflow files
• Admin access to that repository's Actions secrets

Generate your CI key:

1. In Cromus, go to Account → CI and Developer
2. Click Generate to create a CI key (keys begin with cromus_ci_)
3. Copy the key immediately — it is only shown once
4. In GitHub, go to your repo → Settings → Secrets and variables → Actions
5. Add a new secret named CROMUS_API_KEY and paste the key

App 1 — Cromus Gate

What it does

Cromus Gate runs as a GitHub Actions step on every pull request that touches a SKILL.md, AGENTS.md, GRAPH.md, or supported graph JSON file. It sends each file to the Cromus scoring engine, which checks it against:

• The deterministic Croms engine — the same engine used by the in-app validator
• 24 governance rules (prompt hygiene, cost awareness, fallback handling, output constraints, and more)
• Specialist-role rules (on Builder and above) — deeper checks for model selection, budget candidates, and execution target fit

For graph files, Gate normalizes the import into Graph IR and validates bounded paths, declared path budgets, and graph structure. Results carry the graph version/hash identity. Reality Check calibration requires validated observations for that exact identity; CSV path mappings that do not validate are not used for calibration.

The step passes, warns, or blocks the PR based on the result. Gate scoring is unlimited on every plan and never counts against compile allowances.

A file is blocked when either condition is met:

• The Croms score reaches the threshold (default 500 — configurable via score-threshold)
• A Specialist finds an error-severity violation (this blocks independently of the score; a file can be below 500 and still be blocked)

Files below the threshold with no Specialist blocking violations pass, with any warnings attached as annotations.

Example workflow

Create .github/workflows/cromus-gate.yml:

name: Cromus Gate

on:
  pull_request:
    paths:
      - '**.skill.md'
      - '**/SKILL.md'
      - '**/AGENTS.md'

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Score skills
        uses: cromus/cromus-gate-action@v1
        with:
          cromus-api-key: ${{ secrets.CROMUS_API_KEY }}

That is the minimum. On every PR that touches a skill, agent configuration, or graph file, Gate scores each changed file and writes findings as step annotations.

Inputs

Outputs

App 2 — Cromus Compile

What it does

Cromus Compile watches a folder of SOP documents — .md, .txt, .docx, or .pdf. On every push or PR, it sends any changed documents to the Cromus compiler, which extracts workflow steps, identifies tool calls, detects budget candidates, and writes a structured SKILL.md for each document. It then opens (or updates) a pull request containing the generated files.

The compiler drafts. Humans review. The PR is the handoff point. Nothing machine-generated reaches the default branch without human review.

Minimal example

Create .github/workflows/cromus-compile.yml:

name: Compile SOPs to skills

on:
  push:
    paths:
      - 'sops/**'
  pull_request:
    paths:
      - 'sops/**'

permissions:
  contents: write
  pull-requests: write

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Compile SOPs
        uses: cromus/compile-action@v1
        with:
          cromus-api-key: ${{ secrets.CROMUS_API_KEY }}

With Specialist review (also-gate: true)

Add also-gate: 'true' and the compile step scores each generated skill immediately after writing it, appending Specialist findings to the pull request body and writing them as step annotations. No second workflow needed.

name: Compile SOPs with Specialist review

on:
  push:
    paths:
      - 'sops/**'

permissions:
  contents: write
  pull-requests: write

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Compile SOPs to SKILL.md (with Specialist review)
        uses: cromus/compile-action@v1
        with:
          cromus-api-key: ${{ secrets.CROMUS_API_KEY }}
          watch-folder: sops/
          output-folder: skills/
          also-gate: 'true'

Folder layout

Given watch-folder: sops/ and output-folder: skills/, each source document maps to a SKILL.md in a subdirectory named after the document stem:

sops/customer-onboarding.md     →  skills/customer-onboarding/SKILL.md
sops/billing/refund-process.md  →  skills/billing/refund-process/SKILL.md
sops/handoff.docx               →  skills/handoff/SKILL.md

Nested subfolders are included automatically.

Inputs

Outputs

Policy-as-code

Add a cromus.policy.yml to your repository root and the Compile action enforces it automatically after each pull request is created. Violations annotate the skill file and fail the step. The same rules run in the VS Code extension on every save.

Supported rules

Example policy file

# cromus.policy.yml — place in your repository root
version: 1

rules:
  min_croms: 200          # reject skills scoring below 200
  max_cost_per_run: 0.05  # reject skills costing more than $0.05/run
  require_ethos: true     # every skill must have an ethos: block
  allowed_providers:
    - openai
    - anthropic
    - google

Required permissions

The Compile action needs two permissions and nothing else. The Gate action does not require any extra permissions beyond the default read-only access.

permissions:
  contents: write       # push the compiled branch
  pull-requests: write  # open or update the pull request

The full combined setup

This is the recommended repository layout for teams using both apps:

your-repo/
├── sops/                    ← SOP documents live here (Markdown, DOCX, PDF, txt)
│   ├── content-review.md
│   ├── lead-scoring.md
│   └── onboarding-sequence.md
├── skills/                  ← Compiled SKILL.md files live here (auto-generated)
│   ├── content-review/
│   │   └── SKILL.md
│   └── lead-scoring/
│       └── SKILL.md
├── cromus.policy.yml        ← optional policy rules
└── .github/
    └── workflows/
        ├── cromus-compile.yml   ← triggers on push to sops/
        └── cromus-gate.yml      ← triggers on PR touching skills/

What happens on a typical change:

1. Engineer updates sops/lead-scoring.md and pushes to a feature branch
2. Compile runs → generates skills/lead-scoring/SKILL.md → opens a PR
3. Gate runs on that PR → scores the generated skill → posts Specialist findings as annotations
4. Engineer reviews the PR, addresses any flagged issues, and merges
5. Nothing reaches main without a Gate verdict

Use cases

1. White Label agency managing skills across multiple clients

You maintain dozens of AI workflow skill files — one per client process. Without CI, a junior team member can edit a SKILL.md and push changes that introduce budget overruns, missing fallbacks, or a disallowed model. Gate catches these on every PR before they reach production.

Setup: Add Gate to your skills repo. Set fail-on-block: true. Any skill that scores 500+ Croms is blocked — the PR cannot merge until the issues are addressed.

2. Operations team converting legacy SOPs to governed skills

Your ops team keeps process documents in Notion, Confluence, or a shared drive. You export them to Markdown and commit them to a sops/ folder. Instead of manually translating each document into a SKILL.md, Compile does it for you on every push — extracting steps, estimating tool usage, and surfacing budget candidates automatically.

Setup: Point Compile at your sops/ folder with also-gate: 'true'. Every exported document becomes a governed skill draft reviewed by the Specialist before anyone touches it.

3. AI-native product team enforcing model policy before launch

Your team has a policy: no workflow can use a Frontier-tier model for tasks under 500 input tokens. This is easy to audit once — nearly impossible to enforce manually across a growing skill library. Gate enforces it automatically on every PR.

Setup: Gate runs on all PRs touching skills/. The Specialist checks model selection against task complexity and flags mismatches. Engineers see the finding as an annotation before merge.

4. Solo builder running automated quality control

You build AI workflows alone. You don't need a code reviewer, but you do need a second opinion on whether a skill you just wrote is over-engineered or misusing a model. Gate gives you that on every PR — 24 rules, Croms score, and Specialist commentary without waiting on anyone else.

Setup: Fork the minimum Gate setup. Let it run on every PR. Treat the annotations as a mandatory self-review before merge.

5. Enterprise team onboarding new AI engineers

New engineers are productive fast — but they often don't know the team's workflow conventions, approved model lists, or budget expectations. Gate acts as an always-on, always-consistent reviewer that enforces those conventions on day one.

Setup: Gate in blocking mode on the skills/ branch protection rule. Combine with the in-app Skill Studio for interactive skill building, so engineers can see Gate-equivalent feedback before they even open a PR.

6. Compliance-sensitive team maintaining an audit trail

Your industry requires documentation of every AI workflow change — what changed, when, who approved it, and whether it passed governance. Every Gate run is stored in your Cromus account's CI scan history, timestamped and linked to the PR and commit SHA.

Setup: Gate on all PRs, blocking mode. Use the CI History view in Cromus (Account → CI and Developer) to export scan records. Each record shows the skill, the Croms score, the Specialist findings, and the pass/block decision.

Failure behavior

Gate

• If a skill scores ≥ score-threshold (default 500 Croms): the check run is marked failed and the PR is blocked (if fail-on-block: true)
• If a Specialist finds an error-severity violation: the file is blocked regardless of its Croms score — a file can be below 500 and still be blocked
• If a skill is below the threshold and has no Specialist blocking violations: the check run passes with any warnings attached as annotations
• If a skill file cannot be parsed: the step writes an annotation describing the parse error and continues scoring other files
• Gate never fails silently — every result produces a visible annotation

Compile

• If a document cannot be compiled (unsupported format, parse error, or fair-use limit reached): the step writes a named annotation for that document and continues compiling others
• No failure is silent, and no single document failure blocks sibling documents
• If the monthly compile allowance is reached: the step receives a plain-language message with a link to the fair-use policy; Gate steps on the same workflow continue normally

Plan limits

Gate scoring is always unlimited. Compile limits apply only to the document-to-SKILL.md compilation step — once a skill file exists, scoring it with Gate is free and uncapped.

Further reading

• CI Compiler Desk — full Compile reference
• Fair-Use Policy — compile allowances explained
• Croms — what the score measures
• Skill Studio — interactive skill building without CI