Skip to main content

​
Overview

The warden setup-app command creates a GitHub App for Warden with fine-grained permissions and better rate limits compared to using GITHUB_TOKEN.

​
Usage

warden setup-app

​
Interactive Wizard

The command launches an interactive setup: 
$ npx warden setup-app

🔧 Setting up GitHub App for Warden...

🌐 Opening GitHub in your browser...
🔗 https://github.com/settings/apps/new?...

Follow the prompts in your browser to:
  1. Set your app name (e.g., "My Warden Bot")
  2. Review pre-configured permissions
  3. Create the app
  4. Install it on your repositories

Press Enter when you've completed the setup in your browser...

​
Setup Steps

1

Open browser

The command opens GitHub’s app creation page with pre-filled settings:
  • Webhook: Disabled
  • Permissions:
    • Repository: Contents (read), Pull requests (write), Checks (write)
    • Account: None
2

Create the app

In your browser:
  1. Set an app name (e.g., “Warden Bot”)
  2. Review permissions (pre-configured)
  3. Click Create GitHub App
3

Install the app

After creation, you’re redirected to:
  1. Click Install App
  2. Choose repositories:
    • All repositories, or
    • Selected repositories
  3. Click Install
4

Exchange credentials

Return to your terminal and press Enter.Warden exchanges temporary credentials for an installation token:
✓ GitHub App created successfully!
✓ App ID: 123456
✓ Installation ID: 789012
✓ Token saved to ~/.warden/github-app.json
5

Verify setup

Test the integration:
npx warden
Warden automatically uses the app credentials.

​
Benefits Over GITHUB_TOKEN

Better Rate Limits

5,000 requests/hour vs 1,000 with GITHUB_TOKEN

Fine-Grained Permissions

Only read contents and write PRs - no repository admin access

Visible Attribution

PR comments show as your app (e.g., “Warden Bot”) not your personal account

Token Refresh

Tokens refresh automatically - no re-authentication needed

​
Permissions

The app requests these permissions:
PermissionAccessPurpose
ContentsReadRead source code and diff patches
Pull requestsWritePost review comments and suggestions
ChecksWriteCreate check runs with findings summary
Warden never modifies code or repository settings. Write access is only for PR comments and checks.

​
Stored Credentials

Credentials are saved to: 
~/.warden/github-app.json
Content: 
{
  "appId": "123456",
  "installationId": "789012",
  "privateKey": "-----BEGIN RSA PRIVATE KEY-----\n...",
  "createdAt": "2024-03-15T14:30:22Z"
}
Protect this file - it contains your app’s private key. Never commit it to version control.

​
Using in CI/CD

After setup, the app works in both local and CI environments.

​
GitHub Actions

No additional configuration needed:
.github/workflows/warden.yml
jobs:
  warden:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: getsentry/warden@v1
        # No github-token needed - uses app credentials

​
Other CI Systems

Copy credentials to CI environment:
  1. Copy file content: 
    cat ~/.warden/github-app.json
  2. Set as CI secret/variable: WARDEN_GITHUB_APP
  3. In CI, write to file: 
    echo "$WARDEN_GITHUB_APP" > ~/.warden/github-app.json
npx warden

​
Updating the App

To update permissions or settings:
  1. Go to: https://github.com/settings/apps
  2. Click on your app (e.g., “Warden Bot”)
  3. Edit permissions under Permissions & events
  4. Save changes

​
Uninstalling

To remove the app:

​
Remove credentials

rm ~/.warden/github-app.json

​
Uninstall from GitHub

  1. Go to: https://github.com/settings/installations
  2. Find your app (e.g., “Warden Bot”)
  3. Click Configure
  4. Scroll down and click Uninstall

​
Delete the app

  1. Go to: https://github.com/settings/apps
  2. Click on your app
  3. Scroll down and click Delete GitHub App

​
Troubleshooting

Manually open the URL shown in the terminal:
🔗 https://github.com/settings/apps/new?...
Copy and paste into your browser.
The OAuth exchange timed out. Try again:
npx warden setup-app
Complete the browser steps within 5 minutes.
The app isn’t installed on the repo you’re analyzing:
  1. Go to: https://github.com/settings/installations
  2. Click Configure on your app
  3. Add the repository
Install the app on more repositories:
  1. Go to: https://github.com/settings/installations
  2. Click Configure on your app
  3. Select repositories to add
  4. Save
No need to re-run setup-app.
Re-run setup to regenerate credentials:
rm ~/.warden/github-app.json
npx warden setup-app

​
Security Considerations

​
Protect private key

The private key in ~/.warden/github-app.json grants access to your repositories:
  • Never commit to version control
  • Never share publicly
  • Rotate regularly by creating a new app

​
Limit installation scope

Install the app only on repositories that need Warden:
  1. Use Selected repositories during installation
  2. Add/remove repos as needed in settings

​
Monitor usage

Review app activity:
  1. Go to: https://github.com/settings/apps
  2. Click on your app
  3. View Advanced → Payload deliveries (if webhooks enabled)

​
Alternative: Personal Access Token

If you can’t create a GitHub App, use a Personal Access Token: 
export GITHUB_TOKEN=ghp_...
npx warden
Limitations:
  • Lower rate limits (1,000/hour)
  • Broader permissions (repo scope)
  • Comments attributed to your personal account
See Authentication Guide for details.

GitHub Action setup

Set up automated PR reviews

Authentication

All authentication methods

Troubleshooting

Common issues and solutions

Configuration

Configure Warden behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us