Files · Code Sandbox for Jira Service Management SMB IT Teams

# Code Sandbox for Jira Service Management SMB IT Teams
 
> On-demand data analysis sandbox that runs custom Python scripts on Jira Service Management tickets to detect incident trends.
 
A reference solution from [reaatech.com](https://reaatech.com), demonstrating secure code execution triggered by Jira webhooks with budget enforcement, circuit breakers, and structured output repair.
 
## Problem
 
Small IT teams lack real-time insights from Jira Service Management tickets. Manual SQL queries are slow and require technical expertise. This recipe gives analysts a Python sandbox that runs automatically on new tickets and posts structured analysis back as Jira comments.
 
## How It Works
 
1. **Jira webhook** sends ticket creation events to `/api/jira-webhook`
2. **e2b sandbox** is provisioned with pre-installed analytics libraries (numpy, pandas, matplotlib)
3. **@reaatech/agent-budget-engine** caps compute cost per user (soft cap → warn, hard cap → stop)
4. **@reaatech/circuit-breaker-core** halts execution after 3 failures in 5 minutes (gradual recovery)
5. **@reaatech/structured-repair-core** validates JSON script output against a Zod schema before posting back
6. **Jira REST API** (Basic Auth) posts the validated analysis as a ticket comment in Atlassian Document Format
 
## Prerequisites
 
| Variable | Description |
|----------|-------------|
| `E2B_API_KEY` | E2B sandbox API key (from https://e2b.dev) |
| `JIRA_BASE_URL` | Jira Cloud instance URL (e.g. `https://your-domain.atlassian.net`) |
| `JIRA_USER_EMAIL` | Atlassian account email |
| `JIRA_API_TOKEN` | Atlassian API token |
| `JIRA_WEBHOOK_SECRET` | Shared secret for HMAC-SHA256 webhook verification (optional) |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key for execution tracing (optional) |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key (optional) |
| `BUDGET_DEFAULT_LIMIT` | Default per-user compute budget in USD |
| `CIRCUIT_BREAKER_FAILURE_THRESHOLD` | Consecutive failures before circuit opens |
| `CIRCUIT_BREAKER_RECOVERY_TIMEOUT_MS` | Recovery timeout in ms (5 min) |
 
## Setup
 
```bash
pnpm install
cp .env.example .env
# Fill in your credentials
pnpm dev
```
 
## Usage
 
1. Configure a Jira webhook at **Settings → System → Webhooks**:
   - URL: `https://<your-deployment>/api/jira-webhook`
   - Events: `Issue created`
   - Optional: set a secret and add `JIRA_WEBHOOK_SECRET` to your env
2. When a ticket is created, the webhook triggers:
   - Budget check → sandbox launch → Python script execution → output validation → Jira comment
3. The analysis result is posted back to the ticket as a comment with incident trend and insights.
 
## REAA Packages
 
| Package | Role |
|---------|------|
| `@reaatech/agent-budget-engine` | Per-user budget enforcement with soft/hard caps, auto-downgrade, and event-driven alerting |
| `@reaatech/circuit-breaker-core` | State machine circuit breaker (CLOSED ↔ OPEN ↔ HALF_OPEN) with gradual recovery |
| `@reaatech/structured-repair-core` | Six-strategy Zod-driven repair pipeline for malformed JSON outputs |
 
 
## Project Layout
 
```
app/api/jira-webhook/route.ts   Webhook POST endpoint (Next.js App Router)
src/types.ts                    Shared TypeScript interfaces
src/schemas.ts                  Zod validation schemas
src/services/budget.ts          BudgetController wrapper (createBudgetController, check/record/getState)
src/services/circuit-breaker.ts CircuitBreaker wrapper (createSandboxCircuitBreaker, executeWithBreaker)
src/services/tracing.ts         Langfuse observability (createTracer, traceExecution)
src/validation/repair.ts        Structured repair wrappers (validateAndRepair, checkIsValid, diagnoseOutput)
src/sandbox/runner.ts           e2b sandbox lifecycle (create, install deps, runCode, destroy)
src/api/jira.ts                 Jira REST API client (getTicket, postComment, getTicketsInProject)
src/webhook/jira.ts             Webhook payload parser, HMAC verifier, Python script builder
src/index.ts                    Barrel exports + handleWebhook orchestration
src/instrumentation.ts          Next.js instrumentation hook (startup init)
tests/                          9 test modules, 64+ tests, >90% coverage
```
 
## Testing
 
```bash
pnpm test            # vitest run with coverage
pnpm typecheck       # TypeScript strict mode
pnpm lint            # ESLint flat config
```
 
## License
 
MIT — see [LICENSE](./LICENSE).