Skip to main content
Version: Latest

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
      packages: read
      pull-requests: write
      issues: write
    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, license issues, and 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 findings on push to main

4. Customize​

Create .codeward.yaml (or .codeward.json) in your repo root.

Config Format

Both YAML and JSON are fully supported. YAML is shown in examples for readability. See Configuration for JSON equivalents.

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​

  • Browse profiles: Ready-to-use policies for your stack → Codeward Registry
  • 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