live-actions

README

Live Actions - GitHub Actions Monitoring 🚀

⚠️ Beta Software Notice: Live Actions is currently in beta. While functional and actively developed, expect potential instabilities. Please report issues and provide feedback to help us improve!

Real-time monitoring for GitHub Actions workflows and runners. A single self-contained binary — no external databases, no Prometheus server, no Grafana required.

Overview

Live Actions provides real-time monitoring and analytics for GitHub Actions workflows. It works with GitHub Enterprise Cloud and Server at Enterprise, Organization and Repository levels.

🎯 Core Features

📊 Interactive Dashboard

• Live visualization of runner demand with historical charts
• Configurable tracking for GitHub-hosted vs self-hosted runners
• Visual status for queued, running, completed, and failed jobs

📋 Workflow Runs Management

• Complete history of recent workflow executions with pagination
• Click to view individual job information for each workflow run
• Real-time status updates (queued, in_progress, completed, failed)

⚡ Runner Analytics

• Monitor workflow queue times and peak demand periods

📡 Prometheus Metrics

• /metrics endpoint for integration with existing observability platforms
• Compatible with Datadog, New Relic, Splunk, and cloud monitoring services

Quick Start

Option 1: Download Binary

Download the latest release for your platform from the Releases page.

# Set your webhook secret and run
export WEBHOOK_SECRET=$(openssl rand -hex 32)
./live-actions

Open http://localhost:8080 in your browser.

Option 2: Docker

docker run -p 8080:8080 \
  -e WEBHOOK_SECRET=your_secret_here \
  -v live-actions-data:/app/data \
  ghcr.io/gateixeira/live-actions:latest

Configuration

Variable	Default	Description
WEBHOOK_SECRET	(required)	Secret for GitHub webhook validation
PORT	8080	Server port
DATABASE_PATH	./data/live-actions.db	SQLite database file path
LOG_LEVEL	info	Log level (debug, info, warn, error)
ENVIRONMENT	development	Environment (development or production)
TLS_ENABLED	false	Enable HTTPS cookie flags
DATA_RETENTION_DAYS	30	How long to keep historical data
CLEANUP_INTERVAL_HOURS	24	How often to run data cleanup

GitHub Webhook Configuration

1. Generate a secure webhook secret:

   openssl rand -hex 32
   

2. Set the secret in your environment:

   export WEBHOOK_SECRET=your_generated_secret_here
   

3. Configure the GitHub webhook:

   • Payload URL: https://your-domain.com/webhook
   • Secret: Use the secret from step 1
   • Events: Select "Workflow jobs" and "Workflow runs" under "Individual events"
   • Active: ✅ Enabled

Local Development with ngrok

For local development and testing:

# Start the app
make run

# In another terminal, expose via ngrok
ngrok http 8080

Update your GitHub webhook URL to the ngrok HTTPS URL (e.g., https://a1b2c3d4.ngrok.io/webhook).

API Endpoints

Endpoint	Description
GET /	Dashboard UI
GET /healthz	Health check
GET /metrics	Prometheus metrics endpoint
GET /events	Server-Sent Events for real-time updates
POST /webhook	GitHub webhook receiver

Architecture

Live Actions is a single Go binary with all assets embedded:

• Database: SQLite (stored at DATABASE_PATH, default ./data/live-actions.db)
• Frontend: React + Primer (embedded via go:embed)
• Metrics: /metrics endpoint for external Prometheus scraping; charts powered by internal SQLite snapshots

No external services required.

Development

make build    # Build frontend + Go binary
make run      # Run the application
make test     # Run tests
make lint     # Run linter
make clean    # Clean build files

🔥 Live Actions vs GitHub's Built-in Metrics

While GitHub offers Actions Usage Metrics, Live Actions provides real-time operational monitoring:

Feature	GitHub's Metrics	Live Actions
Job Status Tracking	Completed job analysis	Live job status (queued → in_progress → completed)
Update Frequency	Periodic reporting	Instant updates as jobs change state
Queue Monitoring	Retrospective queue times	Real-time queue tracking and demand spikes

Limitations

• Metrics Reconciliation Delays: Slight delays possible due to webhook processing.
• GitHub Webhook Reliability: GitHub may occasionally fail to send events for completed workflow runs.
• Event Ordering: GitHub does not guarantee webhook event order; reordering is handled on a best-effort basis.