pipewatch 0.1.0

Self-learning CI/CD pipeline observability. Zero config. One command.

P I P E W A T C H
Your pipeline is drifting. You just don't know it yet.

---

Self-learning CI/CD pipeline observability CLI. Connects to your CI/CD platform, learns what "normal" looks like using robust statistics, and alerts you when things drift — duration regressions, failure spikes, flaky tests, dependency bloat.

Zero config. One command. Local-first.

Why Pipewatch?

• Your deploy pipeline was 4 minutes last month. Now it's 7. Nobody noticed.
• Test failures crept from 2% to 12% over three weeks. No alert fired.
• A "flaky" test has been randomly failing for months. Everyone ignores it.

Pipewatch catches these problems automatically by building statistical baselines and flagging anomalies — no thresholds to configure, no dashboards to watch.

Install

pip install pipewatch

Requires Python 3.11+.

Quick Start

# 1. Connect to your GitHub repo and build a baseline
export GITHUB_TOKEN=ghp_...
pipewatch init --provider github --repo owner/repo

# 2. Check pipeline health
pipewatch status

# 3. Start watching for drift
pipewatch watch

# 4. Get a full health report
pipewatch doctor

Commands

Command	Description
pipewatch init	Connect to a CI/CD platform and build initial baseline
pipewatch watch	Monitor pipeline for drift in real-time
pipewatch status	Show current pipeline health summary
pipewatch diagnose <run-id>	Deep-dive analysis of a specific run
pipewatch doctor	Generate a full health report (markdown)
pipewatch compare <branch-a> <branch-b>	Compare pipeline behavior between branches
pipewatch budget --stage <name> --max <duration>	Set time budgets per stage
pipewatch notify --slack <url>	Configure Slack/Discord/webhook alerts
pipewatch providers	List supported CI/CD platforms

Examples

# Initialize from GitHub Actions
pipewatch init --provider github --repo myorg/myapp --runs 100

# Watch with custom interval
pipewatch watch --interval 10m

# Diagnose a slow run
pipewatch diagnose 12345678

# Compare main vs feature branch
pipewatch compare main feature/new-api

# Set a 3-minute budget on the "test" stage
pipewatch budget --stage test --max 3m

# Get a health report as markdown (great for PR comments)
pipewatch doctor --output report.md

# Set up Slack notifications
pipewatch notify --slack https://hooks.slack.com/services/...

# Set up Discord notifications
pipewatch notify --discord https://discord.com/api/webhooks/...

How It Works

1. Learn — pipewatch init fetches historical runs and computes per-stage statistical baselines using median + MAD (Median Absolute Deviation), which are resistant to outliers.

2. Detect — pipewatch watch polls for new runs and flags anomalies using Modified Z-scores. No hardcoded thresholds — the baseline adapts to your pipeline.

3. Diagnose — When drift is detected, Pipewatch correlates it to recent commits, dependency changes, and config updates to suggest probable causes.

4. Alert — Send drift alerts to Slack, Discord, or any webhook endpoint.

Architecture

~/.pipewatch/
├── config.yml    # Provider config (no tokens stored)
└── data.db       # SQLite — all data stays local

All analysis uses robust statistics — no ML, no cloud APIs, no training data needed:

• Baseline: Rolling median + MAD (outlier-resistant)
• Drift detection: Modified Z-score
• Trend detection: Mann-Kendall test
• Flaky tests: Bayesian flip-rate analysis

Supported Platforms

Platform	Status
GitHub Actions	Supported
GitLab CI	Coming Soon
Jenkins	Coming Soon
CircleCI	Coming Soon
Bitbucket Pipelines	Coming Soon

Want to add a provider? It's a single Python file — see CONTRIBUTING.md.

Notifications

Pipewatch can send drift alerts to:

• Slack — Rich block-formatted messages
• Discord — Color-coded embeds with fields
• Generic Webhook — JSON payload to any endpoint

# Configure multiple channels
pipewatch notify --slack https://hooks.slack.com/...
pipewatch notify --discord https://discord.com/api/webhooks/...
pipewatch notify --webhook https://your-api.com/alerts

# List configured channels
pipewatch notify --list

# Remove a channel
pipewatch notify --remove slack

Configuration

Pipewatch stores config in ~/.pipewatch/config.yml. Most settings have sensible defaults:

provider: github
repo: owner/repo

baseline:
  window: 50        # Number of runs for baseline computation
  refresh: daily     # How often to recompute baselines

detection:
  z_threshold: 3.0   # Modified Z-score threshold for drift alerts
  trend_window: 20    # Runs to consider for trend detection
  flaky_threshold: 0.1

stages:
  ignore:
    - cleanup        # Stages to exclude from monitoring
  budgets:
    test: 3m         # Time budgets per stage
    build: 5m

notifications:
  channels:
    - type: slack
      webhook: https://hooks.slack.com/...
      events: [drift, failure_spike, flaky_escalation]

Contributing

Contributions are welcome! The easiest way to contribute is adding a new CI/CD provider — each one is a single Python file implementing the PipelineProvider interface.

See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT — see LICENSE for details.