Skip to main content

Quick Start

Get Codeward scanning your PRs in under 3 minutes.

1. Add the GitHub Action​

Create .github/workflows/codeward.yml:

name: Codeward
on:
  pull_request:
  workflow_dispatch:

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read          # checkout
      packages: read          # pull GHCR image
      pull-requests: write    # comment on PRs
      issues: write           # (optional) create/update issues
    steps:
      - uses: codeward-io/[email protected]

That's it. Commit and open a PR.

2. What Happens​

On pull requests: Codeward compares your branch to main and posts a comment showing:

  • New vulnerabilities introduced by your changes
  • New license issues
  • Package changes

On push to main: Codeward scans the current state and creates issues for existing problems.

3. Default Behavior​

With no config file, Codeward uses sensible defaults:

  • Blocks new CRITICAL, HIGH, and MEDIUM vulnerabilities
  • Blocks new UNKNOWN, CRITICAL, and HIGH license issues
  • Warns about existing issues (doesn't block)
  • Posts results to PR comments
  • Creates GitHub issues for existing vulnerabilities and license issues (on push to main)

4. Optional: Customize​

Create .codeward.json in your repo root to customize behavior.

Understanding Rules​

Important: Rules define what to search for, not requirements. When a rule matches, it creates a finding that triggers an action.

  • { "field": "Severity", "type": "eq", "value": "CRITICAL" } searches for CRITICAL severity vulnerabilities
  • When found → triggers the configured action (block, warn, or info)
  • Think "find problems" not "enforce requirements"

Start Non-Blocking (Observe First)​

{
  "vulnerability": [{
    "name": "observe-all",
    "actions": { "new": "warn", "existing": "info" },
    "rules": [
      { "field": "Severity", "type": "eq", "value": "CRITICAL" },
      { "field": "Severity", "type": "eq", "value": "HIGH" }
    ],
    "outputs": [{
      "format": "markdown",
      "destination": "git:pr",
      "fields": ["VulnerabilityID", "PkgName", "Severity", "FixedVersion"],
      "changes": ["new"]
    }]
  }]
}

Block Only Critical​

{
  "vulnerability": [{
    "name": "block-critical",
    "actions": { "new": "block" },
    "rules": [
      { "field": "Severity", "type": "eq", "value": "CRITICAL" }
    ],
    "outputs": [{
      "format": "markdown",
      "destination": "git:pr",
      "fields": ["VulnerabilityID", "PkgName", "Severity", "FixedVersion"],
      "changes": ["new"]
    }]
  }]
}

5. Next Steps​

  • Add more policies: Block risky licenses, track package changes → Policies
  • Configure outputs: JSON files, webhooks, issue creation → Outputs
  • Full config reference: All options explained → Configuration
  • Use Docker: For non-GitHub CI systems → Docker Installation