Config

Warden is configured via warden.toml in your repository root.

version = 1

[[skills]]
name = "security-review"

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]

Skills

Skills define what Warden analyzes and when.

name: Skill name or path (see Skill References)
paths: Files to include (glob patterns)
ignorePaths: Files to exclude (glob patterns)
failOn: Minimum severity to fail: critical, high, medium, low, info, off
reportOn: Minimum severity to report
remote: GitHub repository for remote skills: owner/repo or owner/repo@sha
model: Model override (optional)
maxTurns: Max agentic turns per hunk (optional)

Triggers

Triggers define when a skill runs. Each skill can have one or more triggers. Triggers can override any output setting.

type: pull_request, local, schedule
actions: Event actions for pull_request type
failOn: Override failure threshold for this trigger
reportOn: Override reporting threshold
maxFindings: Override max findings
reportOnSuccess: Override report-on-success behavior
requestChanges: Override REQUEST_CHANGES behavior
failCheck: Override check failure behavior
model: Override model for this trigger
maxTurns: Override max agentic turns

Pull Request Actions

opened: PR created
synchronize: New commits pushed
reopened: PR reopened
closed: PR closed or merged

Filters

Control which files are analyzed using glob patterns. Filters are set at the skill level.

paths: Files to include
ignorePaths: Files to exclude

[[skills]]
name = "api-review"
paths = ["src/api/**/*.ts"]
ignorePaths = ["**/*.test.ts"]

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]

Output

Control how findings are reported. Output settings are set at the skill level or in defaults.

failOn: Minimum severity to fail: critical, high, medium, low, info, off
reportOn: Minimum severity to report
maxFindings: Maximum findings to report
reportOnSuccess: Post comment when no findings. Default: false
requestChanges: Use REQUEST_CHANGES review event when findings exceed failOn. Default: true
failCheck: Fail the check run when findings exceed failOn. Default: false

[[skills]]
name = "security-review"
failOn = "high"
reportOn = "medium"
maxFindings = 20

Defaults

Default settings inherited by all skills. Individual skills can override any setting.

model: Model for all skills
maxTurns: Max agentic turns per hunk. Default: 50
defaultBranch: Repository default branch (auto-detected)
failOn: Default failure threshold
reportOn: Default reporting threshold
maxFindings: Default max findings to report
reportOnSuccess: Post comment when no findings. Default: false
requestChanges: Default REQUEST_CHANGES behavior. Default: true
failCheck: Default check failure behavior. Default: false
ignorePaths: Default paths to exclude
chunking: File processing configuration

[defaults]
model = "claude-sonnet-4-20250514"
maxTurns = 30
failOn = "high"
reportOn = "medium"
requestChanges = true
failCheck = false
ignorePaths = ["**/vendor/**", "**/node_modules/**"]

Chunking

Control how files are split for analysis. By default, Warden analyzes each hunk separately.

File Patterns

per-hunk: Analyze each diff hunk separately (default)
whole-file: Analyze entire file as one chunk
skip: Skip the file entirely

Coalescing

Merge nearby hunks for better context.

enabled: Enable hunk coalescing. Default: true
maxGapLines: Max lines between hunks to merge. Default: 30
maxChunkSize: Target max chunk size in characters. Default: 8000

[defaults.chunking]

[[defaults.chunking.filePatterns]]
pattern = "**/pnpm-lock.yaml"
mode = "skip"

[[defaults.chunking.filePatterns]]
pattern = "**/migrations/*.sql"
mode = "whole-file"

[defaults.chunking.coalesce]
enabled = true
maxGapLines = 50
maxChunkSize = 10000

Schedule Triggers

Run on a cron schedule instead of PR events. Requires paths to specify which files to scan.

issueTitle: Title for the tracking issue. Default: "Warden: {name}"
createFixPR: Create PR with fixes when available. Default: false
fixBranchPrefix: Branch prefix for fix PRs. Default: warden-fix

[[skills]]
name = "security-review"
paths = ["src/**/*.ts"]

[[skills.triggers]]
type = "schedule"
createFixPR = true

Environment Variables

WARDEN_ANTHROPIC_API_KEY: Anthropic API key (required)
WARDEN_MODEL: Model override
WARDEN_SKILL_CACHE_TTL: Cache duration for unpinned remote skills. Default: 24h

Skill References

Skills can be referenced in multiple ways:

# By name (resolved from .agents/skills/ or .claude/skills/)
[[skills]]
name = "security-review"

# By relative path
[[skills]]
name = "./custom-skills/my-review"

# Remote skill (unpinned - checks for updates every 24h)
[[skills]]
name = "security-review"
remote = "getsentry/warden-skills"

# Remote skill (pinned to commit - cached permanently)
[[skills]]
name = "security-review"
remote = "getsentry/warden-skills@abc123def"

Resolution Order

Remote repository (if remote field is specified)
Direct path (if skill contains /, \, or starts with .)
Conventional directories (first match wins)

Skill Files

Skill files define what Warden analyzes. They follow the agentskills.io specification.

Skill Directories

Warden discovers skills from these directories (first match wins):

.agents/skills/: Primary skill directory (recommended)
.claude/skills/: Backup (matches Claude Code convention)

SKILL.md Format

Create a directory with a SKILL.md file:

.agents/skills/
└── security-review/
    └── SKILL.md

The SKILL.md file uses YAML frontmatter for metadata and markdown for the prompt:

---
name: security-review
description: Review code for security vulnerabilities
allowed-tools: Read Grep Glob
---

Review the code for security issues including:
- SQL injection
- XSS vulnerabilities
- Hardcoded secrets
- Insecure dependencies

name: Skill name (must match directory name)
description: Brief description
allowed-tools: Space-separated tool names (optional)

Available Tools

Read, Grep, Glob, Edit, Write, Bash, WebFetch, WebSearch

Workflow

The workflow generated by warden init. Uncomment the GitHub App section for branded comments.

name: Warden

# contents: write required for resolving review threads
permissions:
  contents: write
  pull-requests: write

on:
  pull_request:
    types: [opened, synchronize, reopened]

env:
  WARDEN_ANTHROPIC_API_KEY: ${{ secrets.WARDEN_ANTHROPIC_API_KEY }}

jobs:
  warden:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Uncomment for GitHub App (branded comments)
      # - uses: actions/create-github-app-token@v1
      #   id: app-token
      #   with:
      #     app-id: ${{ secrets.WARDEN_APP_ID }}
      #     private-key: ${{ secrets.WARDEN_PRIVATE_KEY }}

      - uses: getsentry/warden@v0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          # github-token: ${{ steps.app-token.outputs.token }}

Action Inputs

github-token: GitHub token for posting comments. Default: GITHUB_TOKEN
anthropic-api-key: Anthropic API key (falls back to WARDEN_ANTHROPIC_API_KEY)
config-path: Path to config file. Default: warden.toml
fail-on: Minimum severity to fail the check
report-on: Minimum severity to post comments
max-findings: Maximum findings to report. Default: 50
request-changes: Whether to request changes on PR reviews. Default: true
fail-check: Whether to fail the check run. Default: false
parallel: Maximum concurrent trigger executions. Default: 5