Config

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

version = 1

[[triggers]]
name = "Security Review"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "security-review"

Triggers

Triggers map GitHub events to skills.

name: Display name
event: pull_request, issues, issue_comment, schedule
actions: Event actions (required except for schedule)
skill: Skill name or path to run (see Skill References)
remote: GitHub repository for remote skills: owner/repo or owner/repo@sha
model: Model override (optional)
maxTurns: Max agentic turns per hunk (optional)

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.

paths: Files to include
ignorePaths: Files to exclude

[[triggers]]
name = "API Review"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "api-review"

[triggers.filters]
paths = ["src/api/**/*.ts"]
ignorePaths = ["**/*.test.ts"]

Output

Control how findings are reported.

failOn: Minimum severity to fail: critical, high, medium, low, info, off
commentOn: Minimum severity to post as comment
maxFindings: Maximum findings to report
commentOnSuccess: Post comment when no findings. Default: false

[triggers.output]
failOn = "high"
commentOn = "medium"
maxFindings = 20

Defaults

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

model: Model for all triggers
maxTurns: Max agentic turns per hunk. Default: 50
defaultBranch: Repository default branch (auto-detected)
filters: Default path filters
output: Default output settings
chunking: File processing configuration

[defaults]
model = "claude-sonnet-4-20250514"
maxTurns = 30

[defaults.filters]
ignorePaths = ["**/vendor/**", "**/node_modules/**"]

[defaults.output]
failOn = "high"
commentOn = "medium"

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 filters.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

[[triggers]]
name = "Weekly Security Scan"
event = "schedule"
skill = "security-review"

[triggers.filters]
paths = ["src/**/*.ts"]

[triggers.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 .warden/skills/, .agents/skills/, .claude/skills/)
[[triggers]]
skill = "security-review"

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

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

# Remote skill (pinned to commit - cached permanently)
[[triggers]]
skill = "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)

Skills

Skills define what Warden analyzes. They follow the agentskills.io specification.

Skill Directories

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

.warden/skills/: Warden-specific skills (highest priority)
.agents/skills/: Shared agent skills
.claude/skills/: Claude Code skills

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 (referenced by triggers)
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
comment-on: Minimum severity to post comments