Setup

Set up Warden once. It watches every change from there.

Local CLI (Quick Start)

Get started in seconds. No configuration required.

Terminal

# Set your API key
export WARDEN_ANTHROPIC_API_KEY=sk-ant-...

# Run security review on uncommitted changes
npx warden --skill security-review

# Run on specific files
npx warden src/auth.ts --skill security-review

# Run on git changes
npx warden HEAD~3

# Found something? Fix it immediately
npx warden --fix

For more CLI options, see the CLI reference.

GitHub Action Setup

Prerequisites

A GitHub repository
An Anthropic API key (get one here)

1. Add Your API Key

Add your Anthropic API key as a repository secret:

Go to your repository on GitHub
Navigate to Settings → Secrets and variables → Actions
Click New repository secret
Name: WARDEN_ANTHROPIC_API_KEY
Value: Your API key from console.anthropic.com

2. Create the Workflow

Create .github/workflows/warden.yml:

.github/workflows/warden.yml

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

jobs:
  warden:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: getsentry/warden-action@v1
        with:
          anthropic-api-key: ${{ secrets.WARDEN_ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

Action Inputs

Input	Required	Description
`anthropic-api-key`	Yes	Your Anthropic API key
`github-token`	Yes	GitHub token for posting comments (use `secrets.GITHUB_TOKEN`)
`config-path`	No	Path to config file (default: `warden.toml`)
`fail-on`	No	Minimum severity to fail the action: `critical`, `high`, `medium`, `low`
`comment-on`	No	Minimum severity to show in comments: `critical`, `high`, `medium`, `low`. Independent of `fail-on`.

Using a GitHub App (Optional)

By default, Warden uses GITHUB_TOKEN which works well for most setups. However, you can create a dedicated GitHub App for a better experience:

Comments appear from a custom "Warden" bot instead of generic "github-actions"
Fine-grained permissions (only what's needed)
App can be shared across repos in an organization

1. Create the App

Run the setup command to create a GitHub App:

Terminal

# For a personal account
npx warden setup-app

# For an organization
npx warden setup-app --org your-org

This creates an app with the following permissions:

Contents: Read — to access repository files
Pull requests: Write — to post review comments
Issues: Write — to add labels and comments
Checks: Write — to report status
Metadata: Read — required for all apps

2. Install the App

After creating the app, the command outputs an installation URL. Click it to install the app on your repositories. You can choose to install on all repositories or select specific ones.

3. Add Secrets

Add these secrets to your repository (Settings → Secrets and variables → Actions):

WARDEN_APP_ID — The App ID shown after creation
WARDEN_PRIVATE_KEY — The private key (PEM file contents)

4. Update Your Workflow

Modify your workflow to generate a token from the GitHub App:

.github/workflows/warden.yml

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

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

      - 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-action@v1
        with:
          anthropic-api-key: ${{ secrets.WARDEN_ANTHROPIC_API_KEY }}
          github-token: ${{ steps.app-token.outputs.token }}

3. Create the Configuration

Create warden.toml in your repository root:

warden.toml

version = 1

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

Configuration Reference

Triggers

Each trigger maps GitHub events to skills that should run.

warden.toml

[[triggers]]
name = "Security Review"           # Display name
event = "pull_request"             # GitHub event type
actions = ["opened", "synchronize"] # Which actions trigger this
skill = "security-review"          # Skill to run

# Optional: filter by file paths
[triggers.filters]
paths = ["src/**/*.ts"]            # Only run on matching files
ignorePaths = ["**/*.test.ts"]     # Exclude test files

# Optional: output configuration
[triggers.output]
failOn = "high"                    # Fail CI if high+ severity found
commentOn = "high"                 # Only show high+ severity in comments
maxFindings = 10                   # Limit to 10 findings in output
labels = ["security"]              # Always add this label when trigger runs

Supported Events

Event	Actions
`pull_request`	`opened`, `synchronize`, `reopened`, `closed`

Multiple Triggers

You can define multiple triggers for different scenarios:

warden.toml

version = 1

# Run security review on all PRs
[[triggers]]
name = "Security Review"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "security-review"

# Run a custom skill only on specific paths
[[triggers]]
name = "API Review"
event = "pull_request"
actions = ["opened"]
skill = "api-review"

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

Custom Skills

Define custom skills in .warden/skills/.

Verify Setup

Open a pull request to test your configuration. You should see:

The Warden action running in the PR checks
Review comments appearing on the PR if issues are found
A summary comment with all findings

Local Development Workflow

Run Warden locally before pushing to catch issues early. This is faster and cheaper than waiting for CI.

Terminal

# Before committing: check your changes
warden --skill security-review

# Before pushing: check everything since main
warden main..HEAD --skill security-review

# Found issues? Apply fixes automatically
warden --fix

Use --json and --fail-on to integrate with your own CI scripts.