CI/CD Debug Assistant

Reads GitHub Actions logs and finds the line that broke your build. Connect a repository and every failed workflow run comes back diagnosed — the failing line, what category of failure it is, and what to change.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Vercel)                         │
│              Zero-dependency ES modules                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              Go API (Fiber v3, Railway/Render)               │
│                                                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Webhook     │  │ Dashboard   │  │  Analysis Worker    │  │
│  │ Handler     │  │ API         │  │  (rule-based)       │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
         │                  │                    │
         ▼                  ▼                    ▼
┌─────────────┐     ┌─────────────┐      ┌─────────────┐
│ PostgreSQL  │     │   GitHub    │      │  GitHub API │
│  (Neon)     │     │   OAuth     │      │ (go-github) │
└─────────────┘     └─────────────┘      └─────────────┘

The frontend is static HTML/CSS/JS served from Vercel. The Go API runs on Railway (or Render/Fly.io) and handles OAuth, webhooks, and the diagnosis engine. PostgreSQL runs on Neon. The two hosts are cross-site, so the session cookie uses SameSite=None; Secure.

Local Development

Prerequisites

• Go 1.25+
• Docker & Docker Compose (for local PostgreSQL)
• A GitHub OAuth App (create one)
  • Authorization callback URL: http://localhost:8080/auth/github/callback
  • Webhook URL: http://localhost:8080/webhook/github (requires ngrok or similar for testing)

Setup

# Clone and enter the repository
git clone https://github.com/Dixon-O/cicd-debug-assistant.git
cd cicd-debug-assistant

# Copy and configure environment
cp .env.example .env
# Fill in GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_WEBHOOK_SECRET

# Start PostgreSQL
docker compose up -d

# Run migrations and start the API
go run ./cmd/server

The API starts on http://localhost:8080. Health endpoints:

• GET /healthz — liveness
• GET /readyz — readiness (includes database ping)

Build the frontend locally

cd web
API_BASE_URL=http://localhost:8080 node build.mjs
# Outputs to web/dist/
# Serve with: npx serve dist

Deployment

Railway (or Render/Fly.io)

The API can run on any platform that supports Docker and PostgreSQL. Railway and Render both have PostgreSQL add-ons.

1. Create a PostgreSQL database (Neon free tier works)
2. Set environment variables:

   DATABASE_URL=postgres://...
   GITHUB_CLIENT_ID=...
   GITHUB_CLIENT_SECRET=...
   GITHUB_WEBHOOK_SECRET=...
   SESSION_SECRET=<openssl rand -hex 32>
   ENCRYPTION_KEY=<openssl rand -base64 32>
   FRONTEND_URL=https://your-vercel-app.vercel.app
   WEBHOOK_BASE_URL=https://your-api.up.railway.app
   ENVIRONMENT=production
   

3. Deploy from GitHub (Railway auto-detects the Dockerfile)

Vercel (frontend)

cd web
vercel --prod

Set the build command in Vercel settings:

API_BASE_URL=https://your-api.up.railway.app node build.mjs

Output directory: web/dist

The build substitutes the API origin into the HTML, so the dashboard knows where to send requests.

API Endpoints

Method	Path	Auth	Description
GET	/healthz	No	Liveness probe
GET	/readyz	No	Readiness probe (checks DB)
GET	/auth/github	No	Start GitHub OAuth flow
GET	/auth/github/callback	No	OAuth callback
POST	/auth/logout	No	Clear session
GET	/auth/me	Session	Current user info
POST	/webhook/github	HMAC signature	Receive GitHub webhooks
GET	/api/repos	Session	Connected repositories with run stats
GET	/api/repos/available	Session	Repositories available to connect
POST	/api/repos/connect	Session	Connect a repo and register its webhook
DELETE	/api/repos/:id	Session	Disconnect a repo and remove its webhook
GET	/api/runs	Session	Recent pipeline runs
GET	/api/runs/:id	Session	One run with its diagnosis
POST	/api/runs/:id/analyze	Session	Re-run the analysis
GET	/api/stats	Session	Aggregate run counts

The dashboard API routes only register when a database is configured; without DATABASE_URL the server still serves health and auth endpoints.

Development

make test    # go test -race ./...
make lint    # golangci-lint
make fmt     # gofmt + go mod tidy
make vet     # go vet
make build   # production binary into bin/

Tech Stack

• Go 1.25 with Fiber v3, pgx/v5, goose migrations, go-github/v68, golang.org/x/oauth2
• PostgreSQL 16 for users, repositories, runs, and diagnoses
• Zero-dependency frontend — ES modules, no bundler, no framework
• Rule-based diagnosis engine — regex and heuristic patterns, deterministic, no LLM

How It Works

1. User connects a GitHub repository via OAuth
2. Debug Assistant registers a webhook
3. When a workflow run fails, GitHub sends the event
4. The worker downloads logs for failed jobs and runs the diagnosis engine
5. The dashboard shows the failing line, category, and fix

What It Recognizes

• Dependency failures (missing packages, bad versions, lockfile conflicts)
• Test failures (assertion and test name extraction)
• Compilation errors (type, syntax, unresolved imports)
• Missing environment variables and secrets
• Timeouts and OOM kills
• Runner and network failures

License

MIT