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:

  • Warns on new, changed and existing CRITICAL and HIGH vulnerabilities
  • Warns on licence findings with UNKNOWN severity
  • Reports package additions, removals and version changes as info
  • Posts results to PR comments
  • Creates GitHub issues for existing findings on push to main

Nothing in the defaults uses block, so the built-in config never fails a build. Add your own policies to start gating — see Customize below.

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