Forge Health Monitor (Zero-Egress)

A comprehensive example of integrating external services with Atlassian Forge while maintaining full compliance with the "Runs on Atlassian" policy. This project demonstrates how to monitor external services without violating Atlassian's data egress restrictions.

🎯 Project Purpose

This project serves as a reference implementation showing how to:

• Monitor external services from within Atlassian Forge
• Maintain compliance with "Runs on Atlassian" policy
• Use cryptographic authentication for secure communication
• Implement periodic health checks without data egress
• Create a complete monitoring solution with custom backend

📋 What This Application Does

Forge Health Monitor is a monitoring solution that allows you to track the health status of external services directly from your Jira instance. Here's what it does:

🔍 Core Functionality:

• Monitors External Services - Continuously checks if your external APIs, websites, or services are running
• Real-time Status Display - Shows current health status (ALIVE/DOWN) for all monitored services
• User-friendly Interface - Simple Jira global page where you can view all your service statuses
• Automatic Updates - Refreshes status every 5 minutes without manual intervention

🚀 Quick Start

Prerequisites

• Node.js 22+
• Atlassian Forge CLI
• ngrok or similar HTTPS tunnel service

1. Install Dependencies

# Install root dependencies
npm install

# Install Forge UI dependencies
cd static/cusomUI
npm install
cd ../..

# Install custom backend dependencies
cd ./customBackend
npm install
cd ..

2. Set up HTTPS Tunnel

# In a new terminal
ngrok http 8080
# Note the HTTPS URL (e.g., https://abc123.ngrok.app)

3. forge login

forge login

4. register Application(only once)

forge register

5. Configure Forge Variables

# Set the backend URL
forge variables set BACKEND_URL https://abc123.ngrok.app

6. Deploy and Install

# Deploy the Forge app
forge deploy

# Install in your Jira instance
forge install

7. Start Custom Backend

cd customBackend
npm run start

8. First Time Setup

1. Open the Forge app in your Jira instance!
2. Click "Add Service" buttonimg.png
3. Confirm the security dialog - Atlassian will show "Opening external page" dialog
4. Click "Continue" to proceed to the custom backend
5. Enter your health check URL in the custom backend form
6. Complete registration and return to Forge app

🏗️ Architecture Overview

Simple Flow Diagram

Detailed Flow Diagram

Core Components

1. Forge Backend (src/)

   • Atlassian Forge backend with resolvers and web triggers
   • Uses forge-sql-orm as ORM framework with MySQL database
   • Implements cryptographic authentication with Ed25519 key pairs
   • Fully compliant with "Runs on Atlassian" policy

   Resolvers:

   • getTriggerUrlAndBackendUrl - Returns web trigger URL and backend URL
   • getSignature - Generates cryptographic signature for service registration
   • getRecords - Fetches health check records with user information

   Web Triggers:

   • updateItemStatusWeb - Receives health check updates from custom backend
   • clearCacheWeb - Clears application cache
   • invoke-schema-migration - Handles database schema migrations
   • drop-schema-migration - Drops database schema

   Scheduled Triggers:

   • scheduled-schema-migration - Hourly schema migration
   • print-10slowest-queries - Performance analysis every hour
   • clear-cache-trigger - Cache cleanup every 5 minutes

2. Forge CustomUI Application (static/customUI)

   • Atlassian Forge app with Jira global page
   • Displays health check results and service status
   • Handles service registration and user management

3. Custom Backend (customBackend/)

   • External Node.js server for health monitoring
   • Performs periodic health checks (every 5 minutes)
   • Sends results to Forge via static web triggers
   • No data egress - only sends status updates

4. Custom Backend Frontend (customBackend/customBackendFrontend/)

   • Registration interface for new services
   • Service configuration and management
   • User-friendly setup process

Data Flow

The application has two distinct data flows:

1. Service Registration Flow

Forge UI → Forge Backend -> Opening external page → Custom Backend UI → Custom Backend → Forge Backend → Forge UI
(register)  (generate                                  (ask for URL)     (ping service,  (store data)   (display
            signature)                                                    generate keys)                 status)

Detailed Registration Steps:

1. Forge UI - User clicks "Add Service" button
2. Forge Backend - Generates Ed25519 signature (valid for 30 minutes)
3. Forge UI - Initiates redirect to Custom Backend UI with signed state
4. Opening external page - Atlassian security dialog appears, user must confirm
5. Custom Backend UI - Asks user to enter Health Check URL
6. Custom Backend - Pings external service to verify it's accessible
7. Custom Backend - Generates Ed25519 key pairs for tenant
8. Custom Backend - Stores key pairs for current tenant
9. Custom Backend - Sends public key, service info, and status to Forge Backend
10. Custom Backend - Redirects back to Forge application
11. Forge UI - Renders page with external system status

2. Health Monitoring Flow

External Service → Custom Backend → Forge Backend → Forge UI → Jira UI
     (ping)      (health check)   (web trigger)   (resolvers)  (display)

Detailed Monitoring Steps:

1. Custom Backend - Pings external services every 5 minutes
2. Custom Backend - Sends results to Forge via updateItemStatusWeb trigger
3. Forge Backend - Validates signatures and stores/updates records
4. Forge UI - Fetches records via getRecords resolver
5. Jira UI - Displays real-time health status

🔐 Security & Compliance

"Runs on Atlassian" Compliance

• No data egress: All sensitive data stays within Atlassian infrastructure
• External monitoring only: Custom backend only pings external services
• Status updates only: Only health status is sent to Forge
• Tenant isolation: Each tenant has separate data storage

Cryptographic Authentication

• Ed25519 key pairs: Generated per tenant for secure communication
• Signature verification: All requests are cryptographically signed
• 30-minute validity: Signatures expire for security
• Public key registration: Keys are stored securely in Forge

Security Features

• Atlassian Security Dialog: "Opening external page" confirmation required for external redirects
• User Consent: Users must explicitly confirm navigation to external services
• Secure Redirects: All external navigation goes through Atlassian's security layer

Forge Security Dialog

• Default Forge Behavior: The "Opening external page" dialog is a standard Atlassian Forge security feature
• Automatic Trigger: Appears automatically when Forge apps redirect to external URLs
• User Protection: Prevents unauthorized external navigation and protects user data
• Required Confirmation: Users must click "Open" to proceed to external services
• Screenshot Available: Visual reference of the dialog will be added to documentation

📁 Project Structure

├── static/cusomUI/           # Forge application (Jira UI)
│   ├── src/                  # React components and logic
│   ├── build-static/         # Built static files
│   └── README.md            # Forge UI documentation
├── customBackend/            # External monitoring server
│   ├── src/                  # Backend services and routes
│   ├── customBackendFrontend/ # Registration interface
│   └── README.md            # Backend documentation
├── src/                      # Forge backend resolvers
├── manifest.yml             # Forge app configuration
└── README.md                # This file

🔧 Technical Implementation

Forge Backend Resolvers (src/index.ts)

getTriggerUrlAndBackendUrl

• Returns web trigger URL for custom backend communication
• Provides backend URL from environment variables
• Essential for service registration flow
• Triggers Atlassian security dialog when redirecting to external pages

getSignature

• Generates Ed25519 key pairs per tenant
• Creates cryptographic signatures for service registration
• Manages signature expiration (30 minutes)
• Stores signature data in database for verification

getRecords

• Fetches all health check records from database
• Enriches data with user information from Jira API
• Returns combined record and user data for UI display

Web Triggers

updateItemStatusWeb

• Receives health check updates from custom backend
• Validates cryptographic signatures for security
• Handles both REGISTER and UPDATE actions
• Stores/updates health check records in database

clearCacheWeb

• Clears application cache for performance optimization
• Triggered manually or via scheduled tasks

Database Schema

Tables:

• records - Health check data and status
• tenantInfo - Ed25519 key pairs per tenant
• registerNumbers - Signature validation data

ORM Features:

• Type-safe database operations with Drizzle ORM
• Automatic cache invalidation
• Schema migration support
• Performance monitoring and optimization

📚 Documentation

• Forge UI Documentation - Frontend application details
• Custom Backend Documentation - Backend server details
• Custom Backend Frontend Documentation - Registration interface details