Troubleshooting

Quick Diagnosis

Symptom	Likely Cause	Fix
Everything marked "new"	Missing baseline	Mount /main, set CODEWARD_MODE=diff
No PR comment	Missing env vars	Set CODEWARD_GITHUB_TOKEN, PR_NUMBER, OWNER, REPOSITORY
Empty report	Wrong change filter	Include new in changes
Template error with JSON	template set for JSON	Remove template field
Invalid field error	Wrong field for policy type	Check Policies
Relationship filter ignored	Dependency tree disabled	Set global.dependency_tree: true
Rule not working	Misunderstood rule logic	Rules find problems, not enforce requirements

Rule Logic

Common confusion: Rules define what to search for, not requirements.

What You Want	Correct Rule
Find CRITICAL vulns	{ type: eq, value: CRITICAL }
Find large PRs (>30 files)	{ type: gt, value: "30" }
Find missing test script	{ type: not_exists, key: scripts.test }
Find WIP PRs	{ type: contains, value: WIP }
Find Dockerfiles without USER	{ type: not_contains, value: USER }

Think: ✅ "Find what I want to block" — not ❌ "Define requirements".

Docker Volumes

Mount	Purpose	Required
/main	Main/base branch	Yes
/branch	Feature branch	Only for diff mode
/results	Output files	If using file: destinations
/.cache	Trivy DB + license cache	Recommended

Validation Errors

Error	Fix
invalid format	Use markdown, html, or json
invalid destination	Start with git:, log:, file:, or url:
template must be empty	Remove template for JSON outputs
invalid field	Use only allowed fields for the policy type
webhook only valid on url: destinations	Move webhook config to a url: output

Performance Tips

1. Persistent cache — mount /.cache to avoid re-downloading trivy-db
2. Install dependencies — run npm ci, pip install before scanning
3. Air-gapped mode — set TRIVY_SKIP_DB_UPDATE=true with pre-cached DB
4. Limit glob scope — narrow file patterns reduce scan time
5. Pin image versions — use ghcr.io/codeward-io/scan:v0.3.0

Exit Codes

Code	Meaning
0	Success — no blocking findings
1	Failure — block action triggered, or fatal error

Security Notes

• All scanning runs inside the container — no code leaves the runner
• Outputs go only to configured destinations
• No external calls except trivy-db updates and your url: destinations
• Use repository-scoped tokens with minimal permissions
• Grant only: contents: read, packages: read, pull-requests: write, issues: write