Skip to main content

​
EventContext

Complete context about a GitHub event triggering Warden analysis.
​
eventType
GitHubEventType
required
Type of GitHub event:
  • "pull_request" - PR opened, updated, or closed
  • "issues" - Issue opened, edited, or closed
  • "issue_comment" - Comment on issue or PR
  • "pull_request_review" - PR review submitted
  • "pull_request_review_comment" - Comment on PR diff
  • "schedule" - Scheduled cron trigger
​
action
string
required
Specific action within the event type (e.g., "opened", "synchronize", "reopened", "closed")
​
repository
RepositoryContext
required
Information about the repository where the event occurred
​
pullRequest
PullRequestContext
default:"undefined"
Pull request details (only present for PR-related events)
​
repoPath
string
required
Absolute path to the local repository checkout

​
PullRequestContext

Detailed information about a pull request.
​
number
number
required
PR number (must be a positive integer)
​
title
string
required
PR title
​
body
string | null
required
PR description body (null if empty)
​
author
string
required
GitHub username of the PR author
​
baseBranch
string
required
Target branch name (e.g., "main", "develop")
​
headBranch
string
required
Source branch name (e.g., "feature/new-auth")
​
headSha
string
required
Git commit SHA of the head branch (latest commit in the PR)
​
baseSha
string
required
Git commit SHA of the base branch (merge target)
​
files
FileChange[]
required
List of all files changed in the PR

​
RepositoryContext

Information about a GitHub repository.
​
owner
string
required
Repository owner username or organization name
​
name
string
required
Repository name (without owner)
​
fullName
string
required
Full repository name in owner/name format (e.g., "sentry/warden")
​
defaultBranch
string
required
Default branch name (e.g., "main", "master", "develop")

​
FileChange

Information about a single file changed in a pull request.
​
filename
string
required
Path to the file relative to repository root
​
status
FileStatus
required
Type of change:
  • "added" - New file
  • "removed" - Deleted file
  • "modified" - Changed file
  • "renamed" - File moved/renamed
  • "copied" - File copied
  • "changed" - Generic change
  • "unchanged" - No changes (rare)
​
additions
number
required
Number of lines added (must be non-negative)
​
deletions
number
required
Number of lines deleted (must be non-negative)
​
patch
string
default:"undefined"
Unified diff patch showing the changes. May be absent for binary files or very large diffs.
​
chunks
number
default:"undefined"
Number of diff hunks in the patch (calculated automatically if patch is present)

​
GitHubEventType

Supported GitHub event types: 
type GitHubEventType =
  | 'pull_request'
  | 'issues'
  | 'issue_comment'
  | 'pull_request_review'
  | 'pull_request_review_comment'
  | 'schedule';

​
PullRequestAction

Common pull request actions: 
type PullRequestAction =
  | 'opened'      // PR created
  | 'synchronize' // New commits pushed
  | 'reopened'    // PR reopened after being closed
  | 'closed';     // PR closed or merged

​
Example: Pull Request Event Context

import type { EventContext } from '@sentry/warden';

const context: EventContext = {
  eventType: 'pull_request',
  action: 'synchronize',
  repository: {
    owner: 'sentry',
    name: 'warden',
    fullName: 'sentry/warden',
    defaultBranch: 'main'
  },
  pullRequest: {
    number: 42,
    title: 'Add SQL injection detection',
    body: 'Implements new security skill for detecting SQL injection vulnerabilities',
    author: 'security-team',
    baseBranch: 'main',
    headBranch: 'feature/sql-injection-skill',
    headSha: '7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b',
    baseSha: '1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b',
    files: [
      {
        filename: 'src/auth/login.ts',
        status: 'modified',
        additions: 12,
        deletions: 8,
        chunks: 3,
        patch: `@@ -42,8 +42,12 @@
-const query = \`SELECT * FROM users WHERE id = \${userId}\`;
-const user = db.get(query);
+const query = db.prepare('SELECT * FROM users WHERE id = ?');
+const user = query.get(userId);
`
      },
      {
        filename: 'skills/security-audit/SKILL.md',
        status: 'added',
        additions: 45,
        deletions: 0,
        chunks: 1,
        patch: '@@ -0,0 +1,45 @@\n+# Security Audit Skill\n+...'
      }
    ]
  },
  repoPath: '/home/runner/work/sentry/warden'
};

​
Example: Schedule Event Context

import type { EventContext } from '@sentry/warden';

const context: EventContext = {
  eventType: 'schedule',
  action: 'cron',
  repository: {
    owner: 'sentry',
    name: 'warden',
    fullName: 'sentry/warden',
    defaultBranch: 'main'
  },
  pullRequest: undefined, // No PR for scheduled runs
  repoPath: '/home/runner/work/sentry/warden'
};

​
Building Event Context

Warden automatically constructs event context from GitHub Actions environment: 
import { buildEventContext } from '@sentry/warden';
import { Octokit } from '@octokit/rest';

const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

const context = await buildEventContext(
  process.env.GITHUB_EVENT_NAME,      // 'pull_request'
  JSON.parse(process.env.GITHUB_EVENT_PATH), // Event payload
  process.env.GITHUB_WORKSPACE,       // Repository path
  octokit                             // GitHub API client
);
When running locally via CLI, Warden synthesizes a minimal event context based on the current git state.

​
Utility: Counting Patch Chunks

Warden provides a utility to count hunks in a patch: 
import { countPatchChunks } from '@sentry/warden';

const patch = `@@ -10,3 +10,4 @@
 line1
-line2
+line2 modified
+line3 added
 line4
@@ -20,2 +21,2 @@
-old
+new`;

const chunks = countPatchChunks(patch);
// 2 (two @@ headers)

​
Validation

All context types are validated using Zod schemas: 
import {
  EventContextSchema,
  PullRequestContextSchema,
  RepositoryContextSchema,
  FileChangeSchema
} from '@sentry/warden';

// Parse and validate
const validated = EventContextSchema.parse(rawContext);

// Safe parse
const result = EventContextSchema.safeParse(rawContext);
if (!result.success) {
  console.error('Invalid context:', result.error);
}
Warden validates all GitHub event payloads to ensure they contain required fields. Invalid payloads will cause analysis to fail early with clear error messages.

Build docs developers (and LLMs) love

Get started for freeTalk to us