https://github.com/mhbdev/git-pal
Your friendly neighborhood GitPal!
https://github.com/mhbdev/git-pal
ai artificial-intelligence cicd gitops
Last synced: about 1 month ago
JSON representation
Your friendly neighborhood GitPal!
- Host: GitHub
- URL: https://github.com/mhbdev/git-pal
- Owner: mhbdev
- License: other
- Created: 2026-02-01T21:08:17.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-02-09T13:25:57.000Z (about 2 months ago)
- Last Synced: 2026-02-09T14:46:39.701Z (about 2 months ago)
- Topics: ai, artificial-intelligence, cicd, gitops
- Language: TypeScript
- Homepage: https://gitpal.circulo-ai.com
- Size: 3.02 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitPal
GitPal is an automation service that monitors CI failures, diagnoses root causes, and proposes fixes by opening pull requests with audit trails and policy checks.
## Key Capabilities
- Ingests CI failures via webhooks and periodic reconciliation
- Collects logs/artifacts, redacts sensitive data, and stores evidence
- Uses an LLM to diagnose, plan, and generate fixes
- Creates branches, applies changes, and opens PRs/MRs
- Records every step and policy decision for auditability
## Architecture Overview
- **Web app (control plane):** UI, webhook ingestion, configuration, run records
- **Worker (execution plane):** diagnosis, patch generation, verification
- **Data:** Postgres (Drizzle ORM) + object storage for artifacts
- **Queues:** BullMQ for background jobs and retries
## Safety & Governance
- Secret redaction in logs
- File allowlists and policy gates for changes
- Least‑privilege access through provider app installations
- Full audit trail for agent runs
## LLM Configuration
GitPal uses OpenRouter.
Set these in `apps/web/.env`:
```bash
OPENROUTER_API_KEY="your-openrouter-key"
OPENROUTER_MODEL="google/gemini-2.5-flash"
```
## Sandbox Service (Optional)
To enable shallow-clone analysis and richer repo queries, run the sandbox service and set:
```bash
SANDBOX_URL="http://sandbox:8787"
SANDBOX_API_KEY="replace-with-strong-secret"
```
Use the same `SANDBOX_API_KEY` for the web/worker and the sandbox service.
The sandbox runs in a separate container and spawns short‑lived runner containers for each query.
It requires access to the Docker socket to create those runner containers.
Workspace size is capped (see `SANDBOX_MAX_WORKSPACE_BYTES`) and enforced during clone and operations.
Shallow clones are cached per repo+ref for a short TTL; configure `SANDBOX_CACHE_VOLUME` and `SANDBOX_CACHE_TTL_MS`.
## Local Development
1. Configure environment variables
- Copy `apps/web/.env.example` to `apps/web/.env` and fill in values
- Run `pnpm env:check`
- Optional guardrail check for server env access patterns: `pnpm --filter @workspace/web env:guard`
- Optional guardrail check for server console usage policy: `pnpm --filter @workspace/web console:guard`
- Optional module-size guardrail check: `pnpm --filter @workspace/web module:size:check`
2. Install dependencies
- `pnpm install`
3. Start infra + app + worker
- `pnpm dev:local`
To stop infra containers:
- `pnpm dev:infra:down`
## Critical Coverage Gate
Run the critical infrastructure coverage gate locally (web critical paths + DB + sandbox):
```bash
pnpm test:coverage:critical
```
## Operations Runbook
- Rate limiter degraded mode alerts/tuning:
- `docs/operations/rate-limit-degraded-mode-runbook.md`
- `docs/operations/alerts/rate-limit-degraded-alert-templates.md`
- `docs/operations/alerts/rate-limit-threshold-tuning-log.md`
## Background Worker
Run the full stack (app + worker + cron):
```bash
pnpm dev:stack
```
Local reconcile loop env overrides:
- `RECONCILE_INTERVAL_MINUTES` (default: 10)
- `RECONCILE_LOOKBACK_HOURS` (default: 24)
- `RECONCILE_MAX_RUNS` (default: 25)
- `RECONCILE_ALLOW_RETRY_FAILED` (default: false)
- `RECONCILE_RETRY_BACKOFF_MINUTES` (default: 60)
- `RECONCILE_FORCE` (default: false)
- `RECONCILE_PR_LOOKBACK_HOURS` (default: RECONCILE_LOOKBACK_HOURS)
- `RECONCILE_PR_MAX_RUNS` (default: 25)
- `RECONCILE_PR_ALLOW_RETRY_FAILED` (default: false)
- `RECONCILE_PR_FORCE` (default: false)
## Webhook Recovery
If webhooks are missed, GitPal can reconcile recent failures.
```bash
curl -H "authorization: Bearer $CRON_SECRET" \
"http://localhost:3000/api/cron/reconcile-runs?lookbackHours=24&maxRunsPerRepo=25"
```
PR review backfill:
```bash
curl -H "authorization: Bearer $CRON_SECRET" \
"http://localhost:3000/api/cron/reconcile-pr-reviews?lookbackHours=24&maxRunsPerRepo=25"
```
Redis is required in production. Set `REDIS_URL` and keep the worker running.
## Production / Self‑Host
This repo includes a production Dockerfile and Compose stack.
### 1) Create a production env file
```bash
cp apps/web/.env.example .env
```
Fill in required values:
- `DATABASE_URL`, `REDIS_URL`
- `BETTER_AUTH_SECRET`, `JWT_SECRET_KEY`, `PROVIDER_TOKEN_ENCRYPTION_KEY`
- GitHub App secrets (`GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, etc.)
- Public URLs (`NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_API_URL`, `BETTER_AUTH_URL`)
Validate before deployment:
```bash
pnpm env:check:prod -- --env-file=.env
```
### 2) Build and start the stack
```bash
docker compose -f docker-compose.prod.yml up -d --build
```
### 3) Database migrations
The production compose stack runs a one‑shot `migrate` service on deploy and then starts the app services.
### 4) Optional: MinIO for S3‑compatible storage
```bash
docker compose -f docker-compose.prod.yml --profile storage up -d
```
Then set:
- `STORAGE_ENDPOINT`, `STORAGE_BUCKET`, `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY`
### 5) Reverse proxy & HTTPS
Deploy behind a reverse proxy (Caddy/Nginx/Traefik) and terminate TLS there. Ensure `NEXT_PUBLIC_APP_URL` uses HTTPS.
### Services
- **web**: Next.js app + API
- **worker**: BullMQ agent runner
- **cron**: reconciliation scheduler
- **postgres**: database
- **redis**: queue + cache
- **minio**: optional object storage
## GitHub App Setup (Required)
GitPal requires a GitHub App for repository access.
### Required GitHub App configuration
**Development URLs**
- Setup URL: `http://localhost:3000/api/github/app/callback`
- Webhook URL (recommended): `http://localhost:3000/api/webhooks/github`
**Production URLs**
- Setup URL: `https://your-domain.com/api/github/app/callback`
- Webhook URL: `https://your-domain.com/api/webhooks/github`
**Recommended permissions**
- Actions: Read
- Contents: Read & write
- Pull requests: Read & write
- Issues: Read & write
- Metadata: Read
- Organization members: Read (optional)
Install the app on the target repositories. GitPal lists only repos granted to that installation.
## GitHub OAuth (Optional, Login Only)
OAuth is only needed for sign‑in (not repo access).
**Callback URL**
- Dev: `http://localhost:3000/api/auth/oauth2/callback/github`
- Prod: `https://your-domain.com/api/auth/oauth2/callback/github`
**Scopes**
- `read:user`
- `user:email`
## Donate
If GitPal helps your team, consider supporting the project:
- TON: `UQDKcML9_qEz_YsiUtxxIzaEBwCfAiCfKnM1oHIw5qIVO67S`