ActionsPulse 🚀

<div align="center">

Real-time GitHub Actions observability through VS Code with GitHub Copilot

DORA Metrics • Cost Analysis • CI/CD Health • Security Compliance

<img src="docs/images/dashboard-overview.png" alt="ActionsPulse Dashboard" width="100%" style="border-radius: 12px; box-shadow: 0 20px 60px rgba(0,0,0,0.3);" />

_{☝️ <em>This is an actual interactive HTML dashboard generated by ActionsPulse — <a href="#dashboard-tour">see full tour below</a></em>}

</div>

✨ What is ActionsPulse?

ActionsPulse is an Agentic MCP Server that brings DevOps observability directly into your IDE. Ask GitHub Copilot questions like:

💬 "Show me our DORA metrics for the last 30 days" 💬 "Which workflows are costing us the most?" 💬 "Generate a compliance report for SOC2" 💬 "What's our deployment frequency this month?"

And get interactive visual dashboards with actionable insights.

🎯 Features

<a id="dashboard-tour"></a>

🖼️ Dashboard Tour

ActionsPulse generates interactive HTML dashboards that you can open in any browser. Simply ask Copilot:

💬 "Generate DevOps reports for my organization"

Or use the generate_devops_reports tool directly. Here's a complete tour of what you get:

<details open> <summary><strong>📊 Dashboard Overview</strong> — Executive summary with all key metrics at a glance</summary>

<img src="docs/images/dashboard-overview.png" alt="Dashboard Overview" width="100%" style="border-radius: 8px; margin: 16px 0;" />

The main dashboard provides:

• 🎯 DevOps Maturity Score with visual gauge
• 📈 DORA Metrics summary (Deployment Frequency, Lead Time, Change Failure Rate, MTTR)
• ⚡ CI/CD Pipeline health overview
• 💰 Cost analysis highlights
• 🔒 Security & compliance status
• Quick navigation to detailed reports

</details>

<details> <summary><strong>📈 DORA Metrics</strong> — Industry-standard DevOps performance indicators</summary>

<img src="docs/images/dashboard-dora.png" alt="DORA Metrics Dashboard" width="100%" style="border-radius: 8px; margin: 16px 0;" />

Track the four key DORA metrics:

• Deployment Frequency — How often you ship to production
• Lead Time for Changes — Time from commit to production
• Change Failure Rate — Percentage of deployments causing failures
• Mean Time to Restore — How quickly you recover from incidents

Each metric includes trend analysis and benchmarks against industry standards (Elite, High, Medium, Low performers).

</details>

<details> <summary><strong>⚡ CI/CD Pipeline Health</strong> — Workflow performance and reliability</summary>

<img src="docs/images/dashboard-cicd.png" alt="CI/CD Health Dashboard" width="100%" style="border-radius: 8px; margin: 16px 0;" />

Deep dive into your CI/CD pipelines:

• 🔄 Workflow success rates and trends
• ⏱️ Average run times with P95/P99 latencies
• 🚨 Failure analysis and common error patterns
• 📊 Per-repository and per-workflow breakdowns
• 🏃 Queue times and runner utilization

</details>

<details> <summary><strong>💰 Cost Optimization</strong> — Runner costs and savings opportunities</summary>

<img src="docs/images/dashboard-cost.png" alt="Cost Optimization Dashboard" width="100%" style="border-radius: 8px; margin: 16px 0;" />

Understand and optimize your GitHub Actions spending:

• 💵 Total costs by runner type (GitHub-hosted vs self-hosted)
• 📊 Cost breakdown by repository, workflow, and OS
• 🎯 Actionable recommendations for cost savings
• 📈 Spending trends and projections
• ⚡ Efficiency metrics (cost per workflow, cost per minute)

</details>

<details> <summary><strong>🔒 Security & Compliance</strong> — Audit-ready compliance reports</summary>

<img src="docs/images/dashboard-security.png" alt="Security Dashboard" width="100%" style="border-radius: 8px; margin: 16px 0;" />

Stay compliant and secure:

• ✅ Compliance framework coverage (SOC2, ISO27001, HIPAA, PCI-DSS)
• 🔍 Secret scanning status and alerts
• 🛡️ Code scanning findings
• 📋 Branch protection rule compliance
• 🔐 GHAS (GitHub Advanced Security) feature adoption

</details>

<details> <summary><strong>🎓 DevOps Maturity</strong> — Organizational capability assessment</summary>

<img src="docs/images/dashboard-maturity.png" alt="DevOps Maturity Dashboard" width="100%" style="border-radius: 8px; margin: 16px 0;" />

Assess your DevOps maturity level:

• 📊 Overall maturity score with visual gauge
• 🎯 Category scores (CI/CD, Testing, Security, Monitoring, etc.)
• 📈 Improvement recommendations prioritized by impact
• 🏆 Benchmark against industry standards
• 📋 Actionable roadmap for advancement

</details>

💡 How to generate these dashboards: ``` # Ask Copilot in natural language: "Generate DevOps reports for the last 30 days"

>

# Or invoke the tool directly: #generate_devops_reports --timeframe 30d ``` Reports are saved to timestamped folders as standalone HTML files — share them with your team or embed in internal wikis!

🚀 Quick Start

Install from MCP Registry

ActionsPulse is published to the official MCP Registry as io.github.tsviz/actions-pulse.

🌐 Web UI (Recommended) — Use the MCP Registry UI for 1-click installation into VS Code or Cursor:

1. Go to vemonet.github.io/mcp-registry
2. Search for "actions-pulse"
3. Click Install → Select your client (VS Code, Cursor)
4. Configure environment variables when prompted

Manual Docker Setup — Or follow the steps below to configure manually.

Prerequisites

• ✅ Docker installed
• ✅ GitHub Personal Access Token (fine-grained recommended)
• ✅ VS Code with GitHub Copilot

1. Create a Fine-Grained Personal Access Token

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
2. Click Generate new token
3. Configure basic settings:

• Token name: actions-pulse-mcp
• Expiration: 90 days (or per your security policy)
• Resource owner: Select your organization
• Repository access: All repositories

1. Set Repository permissions:

1. Set Organization permissions:

1. Set Organization permissions (continued):

1. Optional permissions (for compliance features, requires GitHub Advanced Security):

1. Click Generate token and save it securely

2. Configure MCP Server

#### Option A: Using env-file (Recommended)

Add to your ~/.mcp.env:

GITHUB_TOKEN=ghp_your_fine_grained_token_here

<details> <summary>📄 mcp.json with env-file</summary>

Add to VS Code's MCP settings (~/.vscode/mcp.json or workspace .vscode/mcp.json):

{
  "servers": {
    "actions-pulse": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/path/to/.mcp.env",
        "-e", "GITHUB_ORG=your-org-name",
        "ghcr.io/tsviz/actions-pulse:latest"
      ],
      "type": "stdio"
    }
  }
}

</details>

#### Option B: Direct Environment Variables

<details> <summary>📄 mcp.json with inline env vars</summary>

{
  "servers": {
    "actions-pulse": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_TOKEN=ghp_your_token",
        "-e", "GITHUB_ORG=your-org-name",
        "ghcr.io/tsviz/actions-pulse:latest"
      ],
      "type": "stdio"
    }
  }
}

</details>

3. Environment Variables Reference

#### Repo Filter Precedence

When determining which repositories to query, ActionsPulse uses this precedence (highest to lowest):

Tip: For quick setup without a config repo, just set DEFAULT_REPO_FILTER in the MCP Registry installer. For richer metadata (team, tier, compliance tags), use inventory.yaml.

4. Configuration Files (Optional)

By default, ActionsPulse queries ALL repositories in your organization via the GitHub API — no configuration files are required. You can filter repos dynamically using tool parameters like repo_filter.

The optional configuration files let you define persistent metadata (teams, tiers, compliance tags) for filtering and reporting. There are two approaches:

#### Option A: Remote Config Repository (Recommended for Teams)

Create a devops-config repository in your organization with the following structure:

devops-config/
├── devops-config.yaml          # Main configuration
├── repositories/
│   └── inventory.yaml          # List of repos to monitor
├── policies/
│   ├── workflow-policies.yaml  # CI/CD standards
│   └── security-policies.yaml  # Security requirements
└── dashboards/                 # Dashboard configs

The MCP server will automatically discover and load from {org}/devops-config repo.

#### Option B: Local Config Files (For Development/Testing)

Mount a local config directory into the Docker container:

<details> <summary>📄 mcp.json with config volume</summary>

{
  "servers": {
    "actions-pulse": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/path/to/.mcp.env",
        "-e", "GITHUB_ORG=your-org-name",
        "-e", "DEVOPS_CONFIG_PATH=/app/config",
        "-v", "/path/to/your/config:/app/config:ro",
        "ghcr.io/tsviz/actions-pulse:latest"
      ],
      "type": "stdio"
    }
  }
}

</details>

#### Repository Inventory Example

<details> <summary>📄 inventory.yaml</summary>

Create repositories/inventory.yaml to define which repos to monitor:

apiVersion: actions-pulse/v1
kind: RepositoryInventory
metadata:
  name: my-inventory
  version: "1.0.0"
  description: "Repositories to monitor"

spec:
  discovery:
    enabled: false  # Only monitor explicit repos

  repositories:
    - name: my-app
      team: platform
      tier: tier-1
      compliance: [SOC2]
      tags: [java, production]

    - name: my-api
      team: backend
      tier: tier-2
      tags: [nodejs, staging]

</details>

#### Repository Tiers Quick Reference

See docs/ARCHITECTURE.md for complete tier definitions, compliance requirements, and alerting behavior.

5. Restart VS Code

After updating mcp.json, restart VS Code to pick up the new MCP server. You can verify the server is running by opening GitHub Copilot Chat and asking about your DevOps metrics.

🛠️ Available Tools

<details> <summary>📊 Usage & Performance Metrics</summary>

get_actions_usage_metrics

Analyze GitHub Actions usage and billing data (basic).

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- timeframe: '24h' | '7d' | '30d'
- breakdown: 'repository' | 'workflow' | 'runner_type'

get_detailed_usage_metrics ⭐

GitHub Insights-style detailed usage metrics with per-workflow, per-job, per-repo, per-OS, and per-runner breakdowns.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- timeframe: '7d' | '30d' | '90d'
- repo_filter: Comma-separated list of repositories (optional)

get_detailed_performance_metrics ⭐

GitHub Insights-style performance metrics with avg run time, queue time, and failure rates per workflow/job/repo/OS/runner.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- timeframe: '7d' | '30d' | '90d'
- repo_filter: Comma-separated list of repositories (optional)

get_actions_performance_metrics

Get workflow performance analytics with P95/P99 latencies (basic).

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- repo_name: Specific repository (optional)
- workflow_id: Specific workflow (optional)
- timeframe: '1h' | '6h' | '24h' | '7d'

</details>

<details> <summary>🏃 Runners & Cost Optimization</summary>

Enhanced Cost Detection: Reports now use a three-tier system for accurate runner cost calculation: - 🎯 API Detection - Uses hosted runners API for exact machine specs - 🏷️ Label Detection - Pattern matching against runner catalog - 📊 Default Pricing - OS-based fallback

>

See Configuration Guide for details.

analyze_runner_utilization

Analyze runner utilization and efficiency.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- runner_type: 'self-hosted' | 'github-hosted' | 'all'
- include_costs: Include cost analysis (default: true)

get_actions_cache_analytics

Analyze Actions cache usage and efficiency.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- repo_name: Specific repository (optional)
- timeframe: '24h' | '7d' | '30d'

generate_cost_optimization_report

Generate actionable cost optimization recommendations.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- include_recommendations: Include actionable recommendations (default: true)
- target_savings_percentage: Target savings (5-50, default: 20)

</details>

<details> <summary>🔍 Workflow Insights & Team Productivity</summary>

get_workflow_insights

Get workflow insights with bottleneck detection.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- repo_name: Repository name (required)
- workflow_name: Workflow name or filename (required)
- analyze_dependencies: Analyze job dependencies (default: true)

get_team_productivity_metrics

Analyze team productivity based on Actions and commit data.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- team_slug: Team slug (optional)
- include_individuals: Include individual metrics (default: false)
- timeframe: '7d' | '30d' | '90d'

get_compliance_audit_report

Generate compliance and security audit report.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- compliance_framework: 'SOC2' | 'ISO27001' | 'HIPAA' | 'PCI-DSS' | 'CUSTOM'
- include_secrets_scan: Include secret scanning (default: true, requires GHAS)

</details>

📊 DORA Metrics & Developer Experience

<details> <summary>📈 DORA Metrics</summary>

get_dora_metrics

Get DORA metrics (Deployment Frequency, Lead Time, Change Failure Rate, Time to Restore).

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- timeframe: '7d' | '30d' | '90d'
- repo_filter: Comma-separated list of repositories (optional)

get_enhanced_dora_metrics

DORA metrics using actual GitHub Deployments API for maximum accuracy.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- timeframe: '7d' | '30d' | '90d'
- repo_filter: Comma-separated list of repositories (optional)

get_pull_request_metrics

Pull request metrics including lead time, merge rates, and size distribution.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- timeframe: '7d' | '30d' | '90d'
- repo_name: Specific repository (optional)
- include_stale: Include stale PR analysis (optional)

get_issue_metrics

Issue metrics including time to close, label distribution, and backlog health.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- timeframe: '7d' | '30d' | '90d'
- repo_name: Specific repository (optional)
- label_filter: Filter by label (optional)

get_deployment_metrics

Deployment metrics from GitHub Deployments API.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- timeframe: '7d' | '30d' | '90d'
- environment: Filter by environment (optional)
- repo_filter: Comma-separated list of repositories (optional)

get_environment_metrics

Analyze GitHub environment configurations including protection rules.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- repo_filter: Comma-separated list of repositories (optional)

get_discussion_metrics

GitHub Discussions metrics including answer rates and engagement.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- repo_name: Specific repository (optional)
- timeframe: '7d' | '30d' | '90d'

get_merge_queue_metrics

Merge queue usage and adoption across repositories.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- repo_name: Specific repository (optional)

</details>

🏷️ Custom Properties

<details> <summary>📋 Custom Properties Tools</summary>

get_org_custom_properties

List all custom property definitions for an organization.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)

get_custom_properties_analytics

Analyze custom property usage and coverage across repositories.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)

get_repos_by_property

Find repositories by custom property value.

Parameters:
- org_name: Organization name (optional if GITHUB_ORG is set)
- property_name: Custom property name (e.g., team, tier, compliance)
- property_value: Property value to filter by (optional)

</details>

🏢 Enterprise Features (Optional)

<details> <summary>⚙️ Enterprise configuration</summary>

If you have GitHub Enterprise, you can enable enhanced features by adding:

GITHUB_ENTERPRISE_SLUG=your-enterprise-slug

This enables:

• Cross-organization billing aggregation
• Enterprise-wide runner pools
• Consolidated audit logs

</details>

🔧 Development

<details> <summary>🛠️ Build and run commands</summary>

Build locally

npm install
npm run build
docker build -t actions-pulse:local .

Run locally (without Docker)

export GITHUB_TOKEN=ghp_your_token
export GITHUB_ORG=your-org
npm start

</details>

🤖 Automating DevOps Reports with GitHub Actions

You can automate DevOps report generation using GitHub Copilot CLI with ActionsPulse MCP server in a GitHub Actions workflow. This enables scheduled weekly reports, on-demand analysis, and automatic issue creation with insights.

How It Works

1. Install Copilot CLI in the workflow runner
2. Configure ActionsPulse MCP with your GitHub token
3. Run Copilot with a prompt to generate reports using MCP tools
4. Create issues with the generated report

Example Workflow

See .github/workflows/weekly-devops-report.yml for a complete working example.

<details> <summary>📄 Key workflow steps</summary>

- name: Setup MCP config
  env:
    GITHUB_TOKEN: ${{ secrets.GH_PAT_DEVOPS }}
  run: |
    mkdir -p ~/.copilot
    printf '%s\n' '{
      "mcpServers": {
        "actions-pulse": {
          "command": "docker",
          "args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN='"$GITHUB_TOKEN"'", "-e", "GITHUB_ORG=your-org", "ghcr.io/tsviz/actions-pulse:latest"],
          "tools": ["*"]
        }
      }
    }' > ~/.copilot/mcp-config.json

- name: Generate DevOps Report
  env:
    GITHUB_TOKEN: ${{ secrets.GH_PAT_DEVOPS }}
    GH_TOKEN: ${{ secrets.GH_PAT_DEVOPS }}
  run: |
    copilot --yolo \
      --disable-builtin-mcps \
      --additional-mcp-config @$HOME/.copilot/mcp-config.json \
      --prompt "Use the actions-pulse MCP tools to generate a DevOps report..."

</details>

Key Copilot CLI Flags

Tips

• Use `$HOME` instead of `~` in the config path — tilde is not expanded in @file arguments
• Embed the token in args — the env block in MCP config doesn't pass variables to Docker
• *Include `"tools": [""]`** in your MCP config — this field is required

📚 Documentation

Example Configurations

Ready-to-use configuration examples are available in the examples/ directory:

�📄 License

MIT