Configuration Overview

Codeward configuration turns governance into code: a single JSON file (config.json) declaring policies (vulnerability, license, package, validation), actions per change category (new | changed | removed | existing – see Glossary), and outputs. Runtime context (repository mounts, event type, GitHub metadata) is supplied via environment variables—kept intentionally outside the versioned policy file.

Design Goals

• Diff‑Aware: Differentiate net‑new risk from historical backlog.
• Policy‑First: All enforcement & reporting flows through explicit, reviewable policy objects.
• Deterministic Outputs: Same inputs + config → stable Markdown/HTML and JSON arrays (safe for automation).
• Low Friction: Only commit what you intend to govern; no absolute host paths or tokens in config.json.

Top-Level Structure

{
  "global": { "dependency_tree": false },
  "vulnerability": [ /* vulnerability policy objects */ ],
  "license": [ /* license policy objects */ ],
  "package": [ /* package policy objects */ ],
  "validation": [ /* validation policy objects */ ]
}

All arrays may be empty. Omit an array entirely if that domain is not used (keeping empty arrays improves clarity for reviewers). Style conventions: Style & Naming Guide.

Global Settings

Key	Type	Effect
dependency_tree	boolean	Adds relationship enrichment fields (Relationship, Parents, Children, Targets) (slight performance cost).

Policy Object (Non‑Validation Types)

{
  "name": "crit-high-block",
  "disabled": false,
  "actions": {"new": "block", "existing": "warn", "removed": "info", "changed": "warn"},
  "rules": [
    {"field": "Severity", "type": "eq", "value": "CRITICAL"},
    {"field": "Severity", "type": "eq", "value": "HIGH"}
  ],
  "outputs": [
    {"format": "markdown", "template": "table", "destination": "git:pr", "fields": ["VulnerabilityID","PkgName","Severity","FixedVersion"], "changes": ["new","existing"], "collapse": true},
    {"format": "json", "destination": "file:/results/vuln-changes.json", "changes": ["new","changed","removed"], "combined": true}
  ]
}

Key points:

• rules is always an array of objects {field,type,value} (OR logic). Never use nested objects keyed by field name.
• Omit unused change keys in actions to reduce noise (canonical order: new, changed, removed, existing).

Validation Policy Differences

Validation adds required keys:

Key	Purpose
type	One of `text
path	Target file / glob / directory
rules	Validation rule objects (shape depends on type)

Example (filesystem):

{
  "name": "require-security-md",
  "type": "filesystem",
  "path": ".",
  "actions": {"new": "block"},
  "rules": [ {"type": "exists", "path": "SECURITY.md"} ],
  "outputs": [ {"format": "markdown", "template": "table", "destination": "git:pr", "title": "Required Governance Files"} ]
}

See: Policy System.

Actions (Per Change Category)

Action	Effect	Typical Use
info	Record only	Baseline visibility
warn	Non‑blocking signal	Socialize standards
block	Fails run (non‑zero exit)	Enforce critical guardrails

Progressive adoption guidance: Progressive Enforcement.

Allowed Fields

Display / filter field reference lives in Policy System. Use only those field names in rules and fields lists.

Output Configuration (Per Policy)

{
  "format": "markdown|html|json",
  "destination": "git:pr|git:issue|file:/path|log:stdout|log:stderr",
  "template": "table|text",        // empty when format=json
  "fields": ["FieldA","FieldB"],  // subset of allowed fields
  "group_by": ["Field"],            // optional grouping
  "changes": ["new","changed"],   // category filter
  "combined": true,                  // merge with other outputs (same dest+format)
  "collapse": true,                  // markdown/html collapsible section
  "title": "Custom Title",
  "comment": "Context line beneath title"
}

Combined semantics & grouping: Combining & Grouping.

Environment & Runtime (Outside config.json)

Variable	Purpose
CI_EVENT	pr enables diff (needs /main & /branch); main single state
GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO, GITHUB_PR_NR	Required for git destinations (context dependent)
CONFIG_PATH	Override config file path
PRIVATE_CONFIG_PATH	Optional private override file
CI	Signals CI context (affects template path resolution)

Mounts (/main, /branch, /results, /.cache) supplied by the Action / Docker.

AI Governance Rationale

Centralizing rules in a diff‑aware config allows rapid, explainable enforcement against AI‑generated or bulk refactors: net‑new critical vulnerabilities or prohibited licenses can block immediately while legacy issues remain visible but non‑blocking until phased enforcement escalates.

Common Mistakes & Fixes

Problem	Cause	Fix
Rules ignored	Used object mapping (e.g., { "severity": [...] })	Use array of { "field": "Severity", ...} objects
Mixed formats in combined output	combined:true across different formats	Keep combined destination uniform (all JSON or all markdown/html)
Empty PR comment	Only existing changes configured	Include new / changed for PR destinations
Everything labeled new	Missing /main mount or CI_EVENT=pr	Provide both volumes + event env var
Validation policy fails	Missing type or path	Add required keys

Best Practices

Goal	Recommendation
Minimize noise	Limit PR outputs to new + changed; send existing elsewhere
Justify blocking	Include Severity, FixedVersion, or Category fields in blocking outputs
Progressive rollout	Start by blocking critical; expand to high after tuning
Observability	Add at least one JSON output per critical policy
Maintainability	Use multiple focused policies instead of a monolith

Example Minimal Config

{
  "vulnerability": [
    {
      "name": "crit-block",
      "actions": {"new": "block", "existing": "warn"},
      "rules": [ {"field": "Severity", "type": "eq", "value": "CRITICAL"} ],
      "outputs": [ {"format": "markdown", "template": "table", "destination": "git:pr", "fields": ["VulnerabilityID","PkgName","Severity","FixedVersion"], "changes": ["new","existing"]} ]
    }
  ],
  "license": [],
  "package": [],
  "validation": []
}

Related Topics

• Policy System
• Diff-Based Analysis
• Main Config Reference
• Output Formats
• Combining & Grouping

---

Next: dive into field/operator details and advanced patterns in the Main Config Reference.