Setup & Configuration

Get AIgileCoach running in minutes.

SaaS (hosted)

1. Register at app.aigilecoach.io/register
2. Follow the setup wizard to connect your Jira server
3. Start using the dashboard

Self-hosted (open source)

git clone https://github.com/gruion/AIgile.git
cd AIgile
docker compose up -d

The app starts at http://localhost:3010 (frontend) and http://localhost:3011 (API).

Environment variables

Jira Connection

Connect AIgileCoach to your Jira Cloud or Server instance.

Jira Cloud

1. Go to Settings in AIgileCoach
2. Enter your Jira Cloud URL: https://yourcompany.atlassian.net
3. Enter your Atlassian email address
4. Generate an API token at id.atlassian.com
5. Click Test Connection — you should see your projects listed
6. Select the projects you want to track and save

Jira Server / Data Center

Same steps, but use your Jira Server URL (e.g. https://jira.yourcompany.com) and a personal access token.

Multiple Jira servers

Team and Enterprise plans support multiple Jira server connections. Each team can be assigned to a different server.

Main Dashboard

Real-time overview of your Jira project.

How it works

Enter a JQL query or select a saved query from the dropdown. The dashboard fetches matching issues and groups them by epic.

What you see

• Stats bar — Total issues, done, in progress, to do, overdue, stale, unassigned
• Epic cards — Each epic shows progress bar, issue count, urgency flags, due dates
• Issue rows — Individual issues with status, assignee, priority, flags, comments
• Quick filters — Filter by All, Critical, Overdue, or Stale

Urgency flags

Auto-refresh

Toggle the Auto-refresh checkbox to reload data every 60 seconds.

Analytics

Status distribution, quality scores, and AI-powered insights.

Features

• Status distribution — Pie/bar charts showing To Do vs In Progress vs Done
• Assignee workload — Issues per team member
• Priority breakdown — Issues by priority level
• AI Coach panel — Ask questions about your project data

JQL Queries & Bookmarks

Save and reuse your favorite JQL queries.

JQL search bar

The search bar at the top of the dashboard accepts any valid JQL query. Press Enter or click Search to execute.

Example queries

project = DEMO ORDER BY status ASC, updated DESC
project = DEMO AND sprint in openSprints()
project = DEMO AND assignee = currentUser()
project = DEMO AND status != Done AND duedate < now()

Bookmarks

Save frequently used queries as bookmarks. Click the bookmark icon next to the search bar to save the current query.

Quick queries

The dropdown shows pre-built queries for each configured project and team, plus your saved bookmarks.

Project Health

Automated board quality assessment and compliance scoring.

How it works

The compliance engine analyzes your project against a set of checks and produces a score from 0-100.

Checks include

• All issues have descriptions and acceptance criteria
• Stories have estimates (story points)
• Issues have assignees
• Due dates are set for upcoming work
• RACI matrix is documented
• Cross-team dependencies are tracked
• WIP limits are respected
• Stale issues are flagged

Suggest Fix

Each failed check includes an AI-generated "Suggest Fix" button that provides a recommended action to improve the score.

Definition of Ready

Check if issues are ready for sprint planning.

Checks

Each issue is scored against these criteria:

• Has a description (>30 characters)
• Has acceptance criteria
• Has a due date
• Has an assignee
• Has story points or time estimate
• Has priority set (not Medium/default)
• Has epic or labels for context

Issues scoring 70%+ are considered "Ready". The page shows distribution and the most common missing criteria.

Backlog Coach

AI-powered backlog review and refinement suggestions.

The Backlog Coach page loads your issues and provides an AI analysis panel. Use the pre-built prompts or ask custom questions about your backlog:

• Which items should be prioritized?
• Are there duplicate or overlapping stories?
• What's missing from the backlog for the next sprint?

Hierarchy View

Navigate your issue tree: epics, stories, subtasks.

Visualizes the parent-child relationships between issues. Expand epics to see their stories, expand stories to see subtasks. Includes stats at each level (done/total, story points).

Sprint Planning

Plan sprints with capacity and priority awareness.

Shows current and upcoming sprints from your Jira board. Displays team capacity, issue assignments, and helps balance workload across the sprint.

Prioritization

AI-assisted issue ranking based on value and urgency.

Analyzes issues using multiple signals (priority, due date, dependencies, staleness) and produces a ranked list. The AI can also generate a prioritization rationale.

Sprint Goals

Define and track sprint-level objectives.

How to use

1. Click New Sprint Goals
2. Enter a sprint name and add goals
3. Link Jira issues to each goal
4. Track status: Not Started, In Progress, Achieved, Missed

Sprint goals persist across sessions and can be reviewed in Sprint Review.

Daily Standup

Auto-generated standup report from Jira activity.

Pulls recent changes from Jira (last 24h by default) and groups them by team member:

• What was done — Issues moved to Done or transitioned forward
• What's in progress — Currently assigned and active
• Blockers — Flagged or stale issues

Flow Metrics

Cumulative flow, cycle time, and throughput analysis.

Cumulative Flow Diagram (CFD)

Shows how issues move through statuses over time. Helps identify bottlenecks (widening bands = work piling up).

Cycle Time

Measures how long issues take from "In Progress" to "Done". Shows percentiles (P50, P85, P95) and individual data points.

Flow Efficiency

Ratio of active work time vs wait time. Higher is better.

Sprint Review

What was completed, velocity trends, and burndown.

Summarizes the sprint: completed vs committed work, velocity compared to previous sprints, and a burndown chart.

Retrospective

Collaborative retro boards with voting.

How to use

1. Create a new retro session
2. Team members add entries in categories: Went Well, To Improve, Action Items, Questions, Shoutouts
3. Vote on entries to prioritize discussion
4. Review and create action items

Gantt Chart

Timeline view of issues with dependencies.

Displays issues on a timeline based on created date and due date. Shows dependencies as arrows between bars.

Dependencies

Map and discover cross-issue and cross-project dependencies.

Dependency view

Shows all issue links (blocks, is blocked by, relates to) as a network graph.

Auto-discover

The Discover Dependencies feature scans multiple projects for cross-project links, shared assignees, and overlapping components — even if no explicit Jira links exist.

PI Board

Multi-team Program Increment planning and tracking.

Overview

Aggregates all configured teams into a single view showing:

• Per-team progress (done/total, story points)
• Cross-team dependencies
• Program board (features across teams and sprints)
• PI compliance score

Configuration

Set up PI dates, sprint count, and sprint duration in Settings. Assign teams to projects and servers.

ROAM Board

Risk and impediment tracking for PI planning.

Categories

Add risks with title, description, severity (low/medium/high/critical), owner, and linked Jira issues.

Team Health Check

Anonymous team sentiment surveys.

How it works

1. Create a health check session
2. Team members vote (1-5) on categories: Mission, Speed, Quality, Fun, Learning, Support, Communication, Autonomy
3. Optional comments per category
4. View aggregated results with green/yellow/red distribution

RACI Matrix

Document team responsibilities and validate assignments.

Creating a RACI matrix

1. Click Create from Template (Project or PI template)
2. Click cells to cycle through: Responsible, Accountable, Consulted, Informed
3. Add custom activities and roles as needed

Validation

The validator checks:

• Every activity has exactly one Accountable (A)
• Every activity has at least one Responsible (R)
• No role is Accountable for too many activities (overload)

AI Suggestions

The Suggest RACI feature analyzes your Jira data to recommend responsibility assignments based on who works on what.

Expertise Map

Discover who knows what across your team.

Analyzes issue history to build a skill/expertise map: who has worked on which components, labels, and issue types. Helps identify SMEs (Subject Matter Experts) and knowledge silos.

AI Coach

AI-powered insights for your project data.

How it works

The AI Coach appears on the Dashboard and Analytics pages. It builds a prompt from your Jira data and sends it to your configured AI provider.

Pre-built prompts

• Full Project Summary — Comprehensive status report covering all epics
• Progress Report — What's done, what's in progress, what's next
• Risks & Blockers — Overdue, stale, and unassigned items
• Upcoming Work — What the team should focus on next
• Epic Health — Per-epic analysis

Copy/paste mode

If no AI provider is configured, the app generates the prompt text. Copy it into ChatGPT, Claude, or any LLM and paste the response back.

Direct integration

Configure an AI provider in Settings to get responses directly in the app (requires Team or Enterprise plan).

AI Provider Setup

Connect your own AI model.

Supported providers

Configuration

Go to Settings → scroll to AI Provider section. Enter your provider, model, and API key. Click Save.

Custom AI Endpoint

The Custom provider lets you connect any HTTP endpoint as your AI backend. This is ideal for:

• n8n workflows — build a webhook that processes prompts through your own AI pipeline
• Make/Zapier — trigger automations with AI responses
• Internal AI services — connect to your company's private LLM or RAG system
• AI agents — any agentic endpoint that accepts a prompt and returns text

Endpoint contract

Your endpoint must accept a POST request with this JSON body:

{
  "prompt": "Analyze this project data...",
  "context": "AIgileCoach agile coaching dashboard",
  "model": "your-model-name",
  "messages": [
    { "role": "system", "content": "You are an agile coach assistant..." },
    { "role": "user", "content": "Analyze this project data..." }
  ]
}

Your endpoint can return any of these formats:

// Any of these work:
{ "response": "Your analysis..." }
{ "text": "Your analysis..." }
{ "content": "Your analysis..." }
{ "output": "Your analysis..." }                    // n8n webhook
{ "choices": [{ "message": { "content": "..." } }] } // OpenAI-compatible
"Plain text response"                                // Raw text

Setup example (n8n)

1. Create an n8n workflow with a Webhook trigger node
2. Add your AI processing nodes (OpenAI, Claude, local LLM, etc.)
3. Return the response as JSON: { "response": "..." }
4. In AIgileCoach Settings, set provider to Custom
5. Enter the n8n webhook URL as the endpoint
6. Optionally add an API key for authentication

Security

• SSRF protection — the app blocks requests to private IPs (10.x, 172.x, 192.168.x), localhost, and cloud metadata endpoints
• Timeout — requests abort after 30 seconds
• Response size limit — 100KB max to prevent memory abuse
• HTML sanitization — HTML tags are stripped from responses to prevent XSS

Settings

Configure Jira servers, teams, and application behavior.

Jira Servers

Add, edit, or remove Jira server connections. Each server needs a URL, email, and API token.

Teams

Define teams and assign them to Jira servers and projects. Each team can have a custom JQL query and color.

Teams vs Projects — what's the difference?

A Jira Project is where issues live in Jira (e.g. BACKEND, MOBILE). A Team in AIgileCoach represents a group of people and links them to a Jira project and server.

JQL Template

Customize how the app finds epic children. Options: auto-detect, parent field (Jira 10+), Epic Link (classic), label-based, component-based.

Import / Export

Export your configuration as JSON for backup. Import to restore or migrate between environments.

Billing & Plans

Manage your subscription (SaaS only).

Plans

Team vs Enterprise — who is each plan for?

Upgrading

Go to Settings → Billing & Plan section. Click the upgrade button — you'll be redirected to Stripe Checkout to enter payment details.

Managing subscription

Click Manage Subscription to open the Stripe Customer Portal where you can update payment method, change plan, view invoices, or cancel.

Health Monitoring

System and tenant health status.

Endpoints

Frontend health page

Visit /health in the app for a visual status dashboard with auto-refresh every 30 seconds.

Performance Settings

Control caching and query limits.

Settings

How caching works

When you run a JQL query, results are cached in memory. Subsequent requests with the same query return instantly from cache until the TTL expires. The cache is per-tenant in SaaS mode.

Result truncation

If a query matches more issues than maxIssuesPerQuery, only the first N issues are fetched. An amber banner appears: "Showing 500 of 12,847 issues." Narrow your JQL query for better results.

Manual refresh

Click the Refresh button on the dashboard to bypass the cache and fetch fresh data from Jira.

API Reference

REST API endpoints for integration and automation.

Authentication

SaaS mode requires a Bearer token in the Authorization header. Get a token via POST /auth/login.

curl -H "Authorization: Bearer YOUR_TOKEN" https://api.aigilecoach.io/config/status

Key endpoints

Audit Log

Track who did what, when — enterprise only.

What gets logged

Every mutating action (POST, PUT, DELETE) by authenticated users is automatically recorded:

• Configuration changes (servers, teams, settings)
• User management (invites, role changes)
• Billing actions (plan changes)
• AI config updates

Viewing the audit log

Admin users can query the audit log via the API:

GET /audit?page=1&limit=50
GET /audit?action=POST&user=alice@company.com

Response

{
  "total": 142,
  "page": 1,
  "limit": 50,
  "entries": [
    {
      "id": "...",
      "action": "POST /config",
      "resource": "server-123",
      "userEmail": "alice@company.com",
      "details": { "statusCode": 200 },
      "ipAddress": "192.168.1.10",
      "createdAt": "2026-03-29T10:30:00Z"
    }
  ]
}

Filtering

Data & Privacy

What data AIgileCoach stores, and what it doesn't.

What we store

What we do NOT store

All Jira data is:

1. Fetched in real-time from your Jira instance on each request
2. Returned directly to your browser
3. Never persisted to disk or database

The only exception is a short-lived in-memory cache (default 5 minutes) that holds recent search results in RAM. This cache:

• Is never written to disk
• Is lost on server restart
• Is scoped per tenant (other tenants cannot access your cached data)
• Can be disabled in Settings (Performance → Cache Enabled)

Collaborative features (in-memory only)

Data from these features is stored in server memory, not in the database:

In SaaS mode, this data is isolated per tenant using namespaced keys.

Security measures

• Jira tokens encrypted at rest with AES-256-GCM
• Passwords hashed with bcrypt (10 rounds)
• JWT tokens signed with HS256, 7-day expiry
• HTTPS enforced via Let's Encrypt on all domains
• Tenant isolation — all queries scoped by tenant ID, no cross-tenant access
• API keys never exposed in responses (masked as ••••••••)

On-premise deployments

For enterprise on-premise: no data ever leaves your network. Everything runs on your infrastructure — database, API, frontend. AIgileCoach servers are never contacted (license validation is offline).

Data deletion

To delete all your data:

• SaaS: Contact contact@aigilecoach.io — we delete your tenant and all associated data within 48 hours
• On-premise: Stop containers and delete the database volume: docker compose down -v

Enterprise SaaS

Enterprise features on the hosted AIgileCoach platform.

What's included

Enterprise SaaS is the same hosted platform as the Team plan, with additional features:

• Unlimited Jira servers, users, teams, RACI matrices
• SSO/SAML — Single sign-on integration (coming soon)
• Audit log — Full activity tracking for compliance
• Custom domain — Use aigile.yourcompany.com via CNAME
• Priority support — Dedicated email, SLA-backed response times

How to upgrade

1. Go to Settings → Billing
2. Click Enterprise — $149/mo
3. Complete payment via Stripe Checkout
4. Enterprise features are enabled immediately

Custom domain setup

1. Contact contact@aigilecoach.io with your desired domain
2. Add a CNAME record: aigile.yourcompany.com → app.aigilecoach.io
3. We configure SSL and routing on our side

SSO/SAML (coming soon)

Enterprise tenants will be able to configure SAML 2.0 SSO with their identity provider (Okta, Azure AD, Google Workspace, etc.). Contact us for early access.

On-Premise Setup

Run AIgileCoach on your own infrastructure.

When to choose on-premise

• Security policy requires data to stay on your network
• Regulatory requirements (data residency, compliance)
• Air-gapped or restricted network environments

Prerequisites

• Docker and Docker Compose installed
• A valid enterprise license key (contact contact@aigilecoach.io)
• Minimum: 2 CPU, 4 GB RAM, 20 GB disk

Installation

# 1. Authenticate with the private registry (token provided with your license)
echo "YOUR_REGISTRY_TOKEN" | docker login ghcr.io -u gruion --password-stdin

# 2. Download the enterprise compose file
curl -O https://raw.githubusercontent.com/gruion/AIgileCoach/main/docker-compose.enterprise.yml
curl -O https://raw.githubusercontent.com/gruion/AIgileCoach/main/.env.enterprise.example

# 3. Configure
cp .env.enterprise.example .env
# Edit .env — add your LICENSE_KEY, REGISTRY_TOKEN, and change passwords

# 4. Pull images and start
docker compose -f docker-compose.enterprise.yml pull
docker compose -f docker-compose.enterprise.yml up -d

# 5. Access
# Frontend: http://localhost:3010
# API:      http://localhost:3011

Configuration

Custom domain / SSL

Put a reverse proxy (nginx, Caddy, Traefik) in front of the containers. Point your domain to the proxy and configure SSL certificates.

Updating

# Authenticate (if not already)
echo "$REGISTRY_TOKEN" | docker login ghcr.io -u gruion --password-stdin

# Pull latest images and restart
docker compose -f docker-compose.enterprise.yml pull
docker compose -f docker-compose.enterprise.yml up -d

Backup

# Database backup
docker exec aigilecoach-db pg_dump -U aigilecoach aigilecoach > backup.sql

# Restore
cat backup.sql | docker exec -i aigilecoach-db psql -U aigilecoach aigilecoach

License Keys

How enterprise licensing works.

How it works

1. You purchase an enterprise license from contact@aigilecoach.io
2. We generate a signed license key for your organization
3. You set it as LICENSE_KEY in your deployment's environment
4. On startup, the API validates the key cryptographically — no phone-home or internet required
5. Enterprise features are unlocked based on the key's contents

What's in a license key

Validation

The key is signed with Ed25519 (asymmetric cryptography). The private key is kept by AIgileCoach; the public key is embedded in the application code. Your deployment can verify the license but cannot generate new ones — no shared secret needed.

Validation happens locally on every request — the API does not contact any external server. If the license expires, enterprise features are automatically disabled.

Checking license status

GET /license/status

Returns:

{
  "licensed": true,
  "plan": "enterprise",
  "tenant": "Acme Corp",
  "maxUsers": "unlimited",
  "features": { "sso": true, "auditLog": true, "customDomain": true },
  "expiresAt": "2027-03-29T00:00:00.000Z",
  "daysRemaining": 365
}

Renewal

When your license approaches expiry, contact us for a renewal key. The old key continues working until its expiry date — there's no interruption during renewal.