Configuration Guide - ActionsPulse MCP Server

This guide covers all configuration options for the ActionsPulse MCP Server.

Environment Variables
MCP Server Configuration
Repository Inventory
DevOps Configuration
Docker Deployment

Environment Variables

Required Variables

Variable	Description	Example
`GITHUB_TOKEN`	GitHub Personal Access Token	`ghp_xxxxxxxxxxxx`
`GITHUB_ORG`	Target GitHub organization to monitor. All API calls use this org.	`my-organization`

Note: GITHUB_ORG is required. There is no "default" organization in GitHub - you must specify which organization to monitor.

Optional Variables

Variable	Description	Default
`DEVOPS_CONFIG_PATH`	Path to config directory	`/app/config`
`LOG_LEVEL`	Logging verbosity	`info`
`ENABLE_METRICS`	Enable Prometheus metrics	`true`
`CACHE_TTL_SECONDS`	API response cache duration	`300`

MCP Server Configuration

VS Code MCP Configuration

The MCP server is configured in your VS Code settings. The configuration file location depends on your OS:

OS	Path
macOS	`~/Library/Application Support/Code/User/mcp.json`
Linux	`~/.config/Code/User/mcp.json`
Windows	`%APPDATA%\Code\User\mcp.json`

Basic Docker Configuration

📄 Basic mcp.json

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

With Custom Configuration Volume

📄 mcp.json with config volume

{
  "servers": {
    "actions-pulse": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_TOKEN=ghp_your_token_here",
        "-e", "GITHUB_ORG=your-org",
        "-e", "DEVOPS_CONFIG_PATH=/app/config",
        "-v", "/Users/you/devops-config:/app/config:ro",
        "ghcr.io/tsviz/actions-pulse:latest"
      ],
      "type": "stdio"
    }
  }
}

Using Environment File

For better security, use an env file instead of inline tokens:

📄 mcp.json with env-file

{
  "servers": {
    "actions-pulse": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/Users/you/.actions-pulse.env",
        "-v", "/Users/you/devops-config:/app/config:ro",
        "ghcr.io/tsviz/actions-pulse:latest"
      ],
      "type": "stdio"
    }
  }
}

📄 .actions-pulse.env

GITHUB_TOKEN=ghp_your_token_here
GITHUB_ORG=your-organization
DEVOPS_CONFIG_PATH=/app/config
LOG_LEVEL=info

Local Development Configuration

For local development without Docker:

📄 mcp.json for local development

{
  "servers": {
    "actions-pulse": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/path/to/actions-pulse",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GITHUB_ORG": "your-org",
        "LOG_LEVEL": "debug"
      },
      "type": "stdio"
    }
  }
}

Repository Inventory

The repository inventory defines which repositories ActionsPulse monitors and analyzes.

File Location

config/
└── repositories/
    └── inventory.yaml

Full Schema

📄 Complete inventory.yaml schema

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

spec:
  # Auto-discovery settings
  discovery:
    enabled: false              # Enable auto-discovery of repos
    includeArchived: false      # Include archived repositories
    includeForked: false        # Include forked repositories
    excludePatterns:            # Glob patterns to exclude
      - "*-archived"
      - "legacy-*"

  # Explicitly defined repositories
  repositories:
    - name: my-app                    # Repository name
      owner: my-org                   # Repository owner (optional if using GITHUB_ORG)
      team: platform-engineering      # Team responsible
      tier: tier-1                    # Service tier (tier-1, tier-2, tier-3)
      compliance:                     # Compliance frameworks
        - SOC2
        - HIPAA
      tags:                           # Custom tags for filtering
        - java
        - springboot
        - production

    - name: my-frontend
      team: frontend
      tier: tier-2
      compliance:
        - SOC2
      tags:
        - react
        - typescript

  # Repository groups for bulk configuration
  groups:
    production:
      repositories:
        - my-app
        - api-gateway
        - auth-service
      tier: tier-1
      team: platform-engineering
      compliance:
        - SOC2
        - PCI-DSS

    staging:
      repositories:
        - my-frontend
        - admin-portal
      tier: tier-2
      team: frontend

Repository Tiers

Tier	Priority	Uptime SLA	Response Time	Use Case
`tier-1`	🔴 Critical	99.9%	< 15 min	Production, revenue-critical
`tier-2`	🟡 Standard	99%	< 1 hour	Internal tools, staging
`tier-3`	🟢 Low	Best effort	< 24 hours	Dev, experimental

See ARCHITECTURE.md for detailed tier documentation.

DevOps Configuration

File Location

config/
└── devops-config.yaml

Configuration Schema

📄 Complete devops-config.yaml schema

apiVersion: actions-pulse/v1
kind: DevOpsConfig
metadata:
  name: actions-pulse-config
  version: "1.0.0"

spec:
  # GitHub configuration
  github:
    organization: your-org
    defaultBranch: main
    
  # Metrics collection settings
  metrics:
    enabled: true
    collectInterval: 300        # Seconds between collections
    retentionDays: 90           # How long to keep metrics
    
  # DORA metrics configuration  
  dora:
    enabled: true
    productionEnvironments:     # Environments to track for deployments
      - production
      - prod
    excludeWorkflows:           # Workflows to exclude from DORA
      - "dependabot/*"
      
  # Alerting thresholds
  alerts:
    failureRateThreshold: 10    # Alert when failure rate exceeds %
    queueTimeThreshold: 300     # Alert when queue time exceeds seconds
    deploymentFrequency:
      warning: 1                # Warn if less than N deployments/day
      critical: 0.1             # Critical if less than N deployments/day
      
  # Compliance settings
  compliance:
    frameworks:
      - SOC2
      - HIPAA
    autoAudit: true
    auditSchedule: "0 0 * * 0"  # Weekly on Sunday

Docker Deployment

Docker Compose

For a complete deployment with monitoring:

📄 docker-compose.yml

version: '3.8'

services:
  actions-pulse:
    image: ghcr.io/tsviz/actions-pulse:latest
    container_name: actions-pulse
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - GITHUB_ORG=${GITHUB_ORG}
      - DEVOPS_CONFIG_PATH=/app/config
      - LOG_LEVEL=info
      - ENABLE_METRICS=true
    volumes:
      - ./config:/app/config:ro
      - ./reports:/app/reports:rw
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "console.log('healthy')"]
      interval: 30s
      timeout: 10s
      retries: 3

Building Locally

🔧 Build and run commands

# Clone the repository
git clone https://github.com/tsviz/actions-pulse.git
cd actions-pulse

# Build
npm install
npm run build

# Build Docker image
docker build -t actions-pulse:local .

# Run
docker run -i --rm \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  -e GITHUB_ORG=your-org \
  actions-pulse:local

Enhanced Runner Cost Detection

ActionsPulse uses a three-tier approach to accurately calculate runner costs, especially for custom-named larger runners.

Detection Methods

Method	Icon	Accuracy	Requirements
API	🎯	Highest	`manage_runners:org` scope + GitHub Enterprise Cloud
Label	🏷️	High	Standard runner labels or patterns like `linux-8-core`
Default	📊	Basic	Falls back to OS-based pricing

How It Works

API Detection (🎯): Fetches actual machine specs from GET /orgs/{org}/actions/hosted-runners
- Returns cpu_cores, memory_gb, storage_gb for each runner
- Works for custom-named larger runners like my-build-runner or runner1
- Requires manage_runners:org scope or Admin organization permission
Label Detection (🏷️): Matches job labels against known patterns
- Standard labels: ubuntu-latest, windows-2022, macos-14
- Larger runner labels: linux-8-core, windows-16-core
- Pattern matching: Extracts 8core from tsvi-linux8cores
Default Detection (📊): Uses OS-based pricing as fallback
- Linux: $0.008/min
- Windows: $0.016/min
- macOS: $0.08/min

Enabling Accurate Cost Detection

📄 PAT Scope Requirements

For most accurate cost detection with custom-named larger runners, add these scopes:

Fine-grained PAT:

Permission	Access	Purpose
`Administration`	Read	Access hosted runners API

Classic PAT:

Scope	Purpose
`manage_runners:org`	Access hosted runners configuration

Example Output

When hosted runner specs are available, cost reports show enhanced detection:

> ✅ **Enhanced cost detection enabled** - Using GitHub Hosted Runners API for accurate larger runner pricing.

| Runner | Detected Type | Runs | Avg Duration | Queue Time | Failure Rate | Est. Cost |
|--------|---------------|------|--------------|------------|--------------|-----------|
| tsvi-linux8cores | 🎯 8-core (linux-x64) | 1 | 2m 31s | 3s | 0.0% | $0.33 |
| ubuntu-latest | 🏷️ ubuntu-latest | 50 | 1m 20s | 2s | 5.0% | $0.53 |
| custom-runner | 📊 linux (standard) | 10 | 0m 45s | 1s | 0.0% | $0.06 |

Troubleshooting

🔧 "Hosted runners API not available"

This means the API returned 404 or 403. Possible causes:

Not on GitHub Enterprise Cloud - The hosted runners API requires Enterprise Cloud
Missing scope - Add manage_runners:org to your PAT
Not an org admin - You need admin access to the organization

Cost detection will fall back to label and default detection.

🔧 Runner costs seem too low

If custom larger runners show standard pricing:

Check if the hosted runners API is accessible (look for "Enhanced cost detection enabled" message)
Ensure runner names/labels contain hints like 8core, linux-8-core, etc.
If using generic names like runner1, runner2, the API detection is required

Security Best Practices

Token Management

Use fine-grained PATs instead of classic tokens
Store tokens in env files, not in mcp.json
Set minimal scopes needed for your use case
Rotate tokens regularly (every 90 days recommended)

Volume Mounts

Use read-only mounts (:ro) for configuration
Use read-write mounts (:rw) only for reports output
Never mount sensitive directories like ~/.ssh or ~/.gnupg

Network Security

Use --network host only when needed for local development
Don't expose ports unless you need external access
Use Docker secrets in production environments

Validation

🔍 Validation commands

# Check if inventory.yaml is valid YAML
cat config/repositories/inventory.yaml | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)"

# Verify Docker can read the config
docker run --rm \
  -v ./config:/app/config:ro \
  ghcr.io/tsviz/actions-pulse:latest \
  cat /app/config/repositories/inventory.yaml

Navigation Menu

Repository navigation

Configuration Guide - ActionsPulse MCP Server

Table of Contents

Environment Variables

Required Variables

Optional Variables

MCP Server Configuration

VS Code MCP Configuration

Basic Docker Configuration

With Custom Configuration Volume

Using Environment File

Local Development Configuration

Repository Inventory

File Location

Full Schema

Repository Tiers

DevOps Configuration

File Location

Configuration Schema

Docker Deployment

Docker Compose

Building Locally

Enhanced Runner Cost Detection

Detection Methods

How It Works

Enabling Accurate Cost Detection

Example Output

Troubleshooting

Security Best Practices

Token Management

Volume Mounts

Network Security

Validation

FilesExpand file tree

CONFIGURATION.md

Latest commit

History

CONFIGURATION.md

File metadata and controls

Configuration Guide - ActionsPulse MCP Server

Table of Contents

Environment Variables

Required Variables

Optional Variables

MCP Server Configuration

VS Code MCP Configuration

Basic Docker Configuration

With Custom Configuration Volume

Using Environment File

Local Development Configuration

Repository Inventory

File Location

Full Schema

Repository Tiers

DevOps Configuration

File Location

Configuration Schema

Docker Deployment

Docker Compose

Building Locally

Enhanced Runner Cost Detection

Detection Methods

How It Works

Enabling Accurate Cost Detection

Example Output

Troubleshooting

Security Best Practices

Token Management

Volume Mounts

Network Security

Validation