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: false
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: false
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 = false
failCheck = false
ignorePaths = ["**/vendor/**", "**/node_modules/**"]

Model precedence: trigger > skill > defaults > CLI flag (-m) > env var (WARDEN_MODEL). Most specific wins.

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 for CI/CD. For local use, Warden can use your Claude Code subscription instead (run claude login).
ANTHROPIC_API_KEY: Fallback if WARDEN_ANTHROPIC_API_KEY is not set
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

Note: Warden restricts execution to read-only tools (Read and Grep) regardless of what the skill declares in allowed-tools. This ensures skills cannot modify your codebase during analysis.

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
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      # 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 }}

Global Workflow With Layered Config

Put the workflow file in your org .github repository to make Warden run everywhere with one mandatory workflow definition. Add the second checkout when you also want one shared base warden.toml so every repo inherits the same baseline skills and defaults.

# .github/.github/workflows/warden.yml in your org .github repo
name: Warden

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:
      - name: Checkout target repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - name: Checkout org GitHub repo
        uses: actions/checkout@v4
        with:
          repository: ${{ github.repository_owner }}/.github
          path: .warden-org

      # 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 }}
          base-config-path: .warden-org/warden.toml
          # Omit this if the base config only uses remote skills
          base-skill-root: .warden-org

The first checkout is the repository being reviewed. The second checkout provides the org-wide base warden.toml and, if needed, local shared skills.

If the target repo also has a root warden.toml, Warden loads that too in the same run. Repo-local config adds more skills and repo-local defaults for those repo-local skills, but it does not weaken org-enforced base skills. Use one global workflow, not separate repo-local Warden workflows.

base-config-path selects the shared base file. base-skill-root points at the checked-out org repo when that base config uses local shared skills. config-path selects the repo-local extension file and still defaults to warden.toml. Repo-local skills and path matching continue to resolve from the analyzed repository root.

If the base config only uses remote skills, you can omit base-skill-root. If it defines local skill names, base-skill-root is required.

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)
base-config-path: Optional path to a base warden.toml that is loaded before the repo config.
base-skill-root: Optional repo root containing local shared skills used by the base config.
config-path: Path to the repo-local warden.toml extension 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: false
fail-check: Whether to fail the check run. Default: false
parallel: Maximum concurrent trigger executions. Default: 5