PatchworkAgent

Kubernetes orchestrator that turns GitHub issues into pull requests using AI agents.

Why this project

This project automates the Issue -> Provider Label -> /agent command -> Pull Request flow: an ai-pr-* label configures the AI worker provider, and an issue comment such as /agent implement starts the worker that clones the repo, solves the problem, and opens a PR.

It avoids AI vendor lock-in with 3 built-in worker providers:

Label	Provider	Backend
`ai-pr-claude`	Claude Code	Anthropic
`ai-pr-codex`	Codex	OpenAI
`ai-pr-aider`	Aider	OpenRouter (extensible)

The source hosting layer is abstracted behind SourceProvider; GitHub is the only built-in source provider today. See docs/adr/0001-source-provider-abstraction.md for the design decision.

The worker architecture is designed to easily add more AI providers (see CONTRIBUTING.md).

Tested on: VPS / 8 GB RAM / 4 vCPU / k3s single-node.

[!IMPORTANT] This repo is a POC and a serious working base. It demonstrates a fully functional flow, but is not production-ready without hardening. See the Security section and SECURITY.md for details.

Architecture

GitHub Issue (ai-pr-* label + /agent implement comment)
       |
       v
  POST /webhook/github
       |
       v
  +-------------------+
  |   Orchestrator     |  Deployment FastAPI
  |   app/app.py       |
  | providers/source   |  GitHub webhook + clone credentials
  +--------+----------+
           | creates a K8s Job based on the AI worker provider
           v
  +----------------+     +----------------+     +----------------+
  | worker-claude  |     | worker-codex   |     | worker-aider   |
  | (Claude Code)  |     | (OpenAI Codex) |     | (Aider/OpenR.) |
  +-------+--------+     +-------+--------+     +-------+--------+
          |                       |                       |
          v                       v                       v
    clone > AI fix > commit > push > PR

Source auth flow: GitHubProvider generates an ephemeral installation token (1h) via GitHub App JWT and returns git clone credentials to the orchestrator. Workers receive only the short-lived token and never receive the PEM key.

Job environment (metadata) : the orchestrator injects source-agnostic variables for each worker Job: SOURCE_REPO, SOURCE_ISSUE_NUMBER, SOURCE_ISSUE_TITLE, SOURCE_ISSUE_BODY (GitHub issue description, bounded to 64 KiB), SOURCE_ISSUE_URL, SOURCE_INSTALLATION_ID, SOURCE_ACTION, SOURCE_TRIGGER, SOURCE_TRIGGER_COMMAND. See docs/adr/0001-source-provider-abstraction.md. The clone credential secret key remains GITHUB_TOKEN (installation token).

Quickstart

1. Prerequisites

A VPS (or machine) with 4 vCPU / 8 GB RAM minimum
API keys for your desired AI worker providers
Ansible option: ansible installed locally + SSH root access to the VPS
Manual option: k3s, Docker, and kubectl installed on the VPS

2. Deployment

Option A: Ansible (recommended)

The Ansible playbook installs everything on a bare VPS (k3s, Docker, images, secrets, deploy).

cd ansible

# 1. Edit the inventory with your VPS IP/hostname
vim inventory.ini

# 2. Edit the variables (secrets, domain, images)
vim group_vars/vps.yml

# 3. Run the deployment
ansible-playbook -i inventory.ini playbook.yml \
  --extra-vars "ingress_host=code-agent.yourdomain.com" \
  --extra-vars "traefik_acme_email=you@yourdomain.com" \
  --extra-vars "github_app_id=123456" \
  --extra-vars "webhook_secret=$(openssl rand -hex 32)" \
  --extra-vars "admin_token=$(openssl rand -hex 32)" \
  --extra-vars "anthropic_api_key=sk-ant-xxxxx" \
  --extra-vars "github_private_key_local_path=/path/to/app.pem"
  # Optional: --extra-vars "openai_api_key=sk-xxxxx"
  # Optional: --extra-vars "openrouter_api_key=sk-or-xxxxx"

Secrets passed via --extra-vars are not committed. See ansible/group_vars/vps.yml for the full list of variables.

Option B: Manual

# Namespace, RBAC, network policies
kubectl apply -f k8s/namespace-rbac.yaml
kubectl apply -f k8s/networkpolicy.yaml

# Secrets (never commit real values)
kubectl -n ai-bot create secret generic github-app \
  --from-literal=GITHUB_APP_ID=<app-id> \
  --from-file=GITHUB_PRIVATE_KEY=/path/to/app.pem

kubectl -n ai-bot create secret generic github-webhook-secret \
  --from-literal=WEBHOOK_SECRET=<your-secret>

kubectl -n ai-bot create secret generic orchestrator-config \
  --from-literal=JOB_TTL_SECONDS=3600 \
  --from-literal=ADMIN_TOKEN=<strong-random-token>

# At least one provider (example: Claude)
kubectl -n ai-bot create secret generic anthropic-api-key \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-xxxxx

# Build and import images
docker build -f images/orchestrator/Dockerfile -t ghcr.io/<your-org>/orchestrator:latest .
docker save ghcr.io/<your-org>/orchestrator:latest | sudo k3s ctr images import -

docker build -f images/worker-claude/Dockerfile -t worker-claude:latest .
docker save worker-claude:latest | sudo k3s ctr images import -

docker build -f images/worker-codex/Dockerfile -t worker-codex:latest .
docker save worker-codex:latest | sudo k3s ctr images import -

docker build -f images/worker-aider/Dockerfile -t worker-aider:latest .
docker save worker-aider:latest | sudo k3s ctr images import -

# Deploy
kubectl -n ai-bot apply -f k8s/orchestrator.yaml

3. GitHub App

Create a GitHub App with:
- Permissions: Contents (RW), Pull requests (RW), Issues (RW)
- Subscribe to event: Issues
Install the app on target repos
Configure the webhook URL:
- With a domain: https://code-agent.yourdomain.com/webhook/github
- Without a domain (testing): kubectl -n ai-bot port-forward svc/orchestrator 8080:80 + tunnel (ngrok, SSH)

4. Usage

Add a label ai-pr-claude, ai-pr-codex, or ai-pr-aider to configure the provider, then comment /agent implement on the issue. The bot creates a PR.

Migration note: TRIGGER_PREFIX has been removed. Use PROVIDER_LABEL_PREFIX to configure provider label matching.

Configuration

Kubernetes Secrets

Secret	Keys	Used by
`github-app`	`GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY`	orchestrator
`github-webhook-secret`	`WEBHOOK_SECRET`	orchestrator
`orchestrator-config`	`JOB_TTL_SECONDS`, `ADMIN_TOKEN`	orchestrator
`anthropic-api-key`	`ANTHROPIC_API_KEY`	worker-claude
`openai-api-key`	`OPENAI_API_KEY`	worker-codex
`openrouter-api-key`	`OPENROUTER_API_KEY`	worker-aider

Update a secret:

kubectl -n ai-bot delete secret <name> --ignore-not-found && \
kubectl -n ai-bot create secret generic <name> --from-literal=<KEY>=<value>

Verify:

kubectl -n ai-bot get secrets
kubectl -n ai-bot get secret anthropic-api-key -o jsonpath='{.data.ANTHROPIC_API_KEY}' | base64 -d

Docker Images

Image	Dockerfile
`ghcr.io/hey-intent/orchestrator:latest`	`images/orchestrator/Dockerfile`
`worker-claude:latest`	`images/worker-claude/Dockerfile`
`worker-codex:latest`	`images/worker-codex/Dockerfile`
`worker-aider:latest`	`images/worker-aider/Dockerfile`

Rebuild and reimport after changes:

docker build -f images/<image>/Dockerfile -t <image-name>:latest .
docker save <image-name>:latest | sudo k3s ctr images import -
# For orchestrator: kubectl -n ai-bot rollout restart deployment/orchestrator
# For a worker: rerun the corresponding debug job

Webhook and Ingress

The Ingress (k8s/orchestrator.yaml) exposes only /webhook/github via Traefik with TLS Let's Encrypt. Adjust the host and annotations if you use a different ingress controller.

Operations

Orchestrator

kubectl -n ai-bot logs -f deploy/orchestrator --tail=200    # logs
kubectl -n ai-bot rollout status deployment/orchestrator     # status
kubectl -n ai-bot rollout restart deployment/orchestrator    # restart

Debug Jobs

These jobs verify CLI installation and API key. Do not use in production.

# Run / logs / shell / rerun (replace <provider> with claude, codex, or aider)
kubectl -n ai-bot apply -f k8s/debug-<provider>.yaml
kubectl -n ai-bot logs -f job/debug-<provider>
kubectl -n ai-bot exec -it job/debug-<provider> -- /bin/sh
kubectl -n ai-bot delete job debug-<provider> --ignore-not-found && kubectl -n ai-bot apply -f k8s/debug-<provider>.yaml

Manual Jobs (ai-issue)

Manual jobs in k8s/ai-issue-*.yaml must set SOURCE_REPO, SOURCE_ISSUE_NUMBER, and SOURCE_INSTALLATION_ID (not the old GITHUB_* names).

# Run / logs / rerun (replace <provider>)
kubectl -n ai-bot apply -f k8s/ai-issue-<provider>.yaml
kubectl -n ai-bot logs -f job/ai-issue-<provider>-manual
kubectl -n ai-bot delete job ai-issue-<provider>-manual --ignore-not-found && kubectl -n ai-bot apply -f k8s/ai-issue-<provider>.yaml

Overview

kubectl -n ai-bot get pods,jobs,deploy,svc
kubectl -n ai-bot get events --sort-by=.metadata.creationTimestamp

Admin (local port-forward only)

kubectl -n ai-bot port-forward svc/orchestrator 8080:80
curl -s -X POST http://127.0.0.1:8080/jobs/run -H "Authorization: Bearer <ADMIN_TOKEN>"

Security

Threat Model

Surface	Risk	Mitigation
Incoming webhook	Fake webhook to trigger a job	HMAC-SHA256 signature (`WEBHOOK_SECRET`) verified on every request
Admin endpoints	Unauthorized access	Bearer token (`ADMIN_TOKEN`), not exposed via Ingress
Source-provider private key	Theft = source repo access	Secret stays in orchestrator pod only; workers receive short-lived clone credentials
GitHub token (workers)	Compromised worker	Token stored in ephemeral K8s Secret (ownerReference to Job), scoped to one installation, expires in 1h, ephemeral container
AI API keys	Leak	Injected via K8s `secretKeyRef`, one secret per AI worker provider
AI / LLM input	Issue title & body influence model behavior	Content is user-controlled; bounded length in Job env; treat as untrusted input (prompt injection). See `SECURITY.md`
Git credentials	Token in logs	Auth via `GIT_ASKPASS`, no token in URLs
K8s RBAC	Out-of-scope access	Role limited to `ai-bot` namespace, workers without ServiceAccount

Production Recommendations

Use a secrets operator (Sealed Secrets, External Secrets)
Restrict RBAC access to Secrets and Jobs
Monitor jobs > 30 min (token expires at 1h)
Regularly rotate WEBHOOK_SECRET and ADMIN_TOKEN
Review any new SourceProvider for webhook verification, credential scope, and logging behavior
See SECURITY.md for vulnerability reporting and provider security rules

Troubleshooting

Symptom	Diagnostic
`ErrImageNeverPull`	Image not imported into k3s (`docker save ... \| sudo k3s ctr images import -`)
`CrashLoopBackOff`	`kubectl logs pod/<pod> --previous`
`Not logged in`	Missing API secret (depends on provider)
`Pods Pending`	`kubectl describe pod <pod>`
`Job missing SOURCE_REPO` / clone fails	Orchestrator + worker images out of sync; manual YAML still using `GITHUB_REPO` / `GITHUB_ISSUE_` — use `SOURCE_` envs
Job 409 conflict	Job already exists, `kubectl delete job <name>`

kubectl -n ai-bot get all
sudo k3s ctr images list | grep -E 'worker|orchestrator'
sudo systemctl status k3s --no-pager -l

File Structure

.
|-- app/
|   |-- app.py                  # FastAPI Orchestrator
|   |-- config.py               # Runtime env/config
|   `-- requirements.txt
|-- images/
|   |-- orchestrator/Dockerfile
|   |-- worker-claude/          # Dockerfile + run.sh
|   |-- worker-codex/
|   `-- worker-aider/
|-- k8s/
|   |-- namespace-rbac.yaml
|   |-- networkpolicy.yaml
|   |-- orchestrator.yaml        # Deployment + Service + Ingress
|   |-- ai-issue-*.yaml         # Manual jobs per provider
|   |-- debug-*.yaml            # Debug jobs per provider
|   `-- secrets/                # Templates (no values)
|-- prompt/
|   |-- action_prompt.sh       # Dispatches prompts by SOURCE_ACTION
|   `-- actions/               # Action-specific worker prompts
|-- providers/
|   |-- source/                 # SourceProvider interface + GitHub implementation
|   |-- git_workflow.sh         # Shared Git logic
|   |-- claude_code.sh
|   |-- openai.sh
|   `-- aider.sh
|-- ansible/
|   |-- playbook.yml            # Full VPS deployment
|   |-- inventory.ini
|   |-- inventory-local.ini
|   |-- inventory-prod.ini      # gitignored
|   |-- requirements.yml        # Ansible collections
|   `-- group_vars/vps.yml
|-- docs/
|   |-- adr/                    # Architecture decision records
|   `-- workspace.dsl           # C4 architecture (Structurizr)
|-- .github/
|   `-- workflows/secret-scan.yml  # CI secret scanning
|-- CONTRIBUTING.md
|-- SECURITY.md
`-- LICENSE (MIT)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

PatchworkAgent

Why this project

Architecture

Quickstart

1. Prerequisites

2. Deployment

Option A: Ansible (recommended)

Option B: Manual

3. GitHub App

4. Usage

Configuration

Kubernetes Secrets

Docker Images

Webhook and Ingress

Operations

Orchestrator

Debug Jobs

Manual Jobs (ai-issue)

Overview

Admin (local port-forward only)

Security

Threat Model

Production Recommendations

Troubleshooting

File Structure

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
ansible		ansible
app		app
docs		docs
images		images
k8s		k8s
prompt		prompt
providers		providers
tests		tests
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
illustration.png		illustration.png
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt

Folders and files

Latest commit

History

Repository files navigation

PatchworkAgent

Why this project

Architecture

Quickstart

1. Prerequisites

2. Deployment

Option A: Ansible (recommended)

Option B: Manual

3. GitHub App

4. Usage

Configuration

Kubernetes Secrets

Docker Images

Webhook and Ingress

Operations

Orchestrator

Debug Jobs

Manual Jobs (ai-issue)

Overview

Admin (local port-forward only)

Security

Threat Model

Production Recommendations

Troubleshooting

File Structure

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages