Shithub

Shithub is a GitHub-style self-hosted Git platform with a FastAPI backend, React frontend, Celery workers, and a CLI.
It supports repository hosting over Smart HTTP, async AI automations (README + code build), and JWT-based authentication.

Features

• Repository create/list/delete
• Git Smart HTTP clone/push via /repos/*
• Email/password registration/login with JWT session auth
• Optional profile picture upload and avatar display
• AI README generation jobs with status and logs
• sh*tAI build jobs from natural-language prompts
• bugAI coding assistant page for Q&A with optional repo context
• Monaco-based web editor with multi-file tabs and Save & Commit
• AI autocomplete in editor (insert-at-cursor suggestions)
• AI-generated commit messages in editor save flow
• Web UI + CLI workflows

Architecture

Frontend / CLI -> FastAPI -> SQLite + bare repos + Celery/Redis -> LLM providers

Prerequisites

• Python 3.11+
• Node.js 18+
• Git
• Redis (for background jobs)

Run Locally (Full Stack)

1. Backend API

python -m venv .venv
# Windows PowerShell
. .venv/Scripts/Activate.ps1
# Linux/macOS
# source .venv/bin/activate

pip install -r requirements.txt
uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

2. Redis

redis-server

3. Celery worker

celery -A backend.worker.celery_app.celery worker --loglevel=info

4. Frontend

cd frontend
npm install
npm run dev

Default local URLs:

• Frontend: http://localhost:5173
• Backend: http://127.0.0.1:8000

Deploy on Render (Docker + CI/CD)

This repo now includes:

• Dockerfile.backend (FastAPI via Gunicorn + Celery worker in same container)
• Dockerfile.frontend (Vite build + Nginx SPA serving + /api/* proxy)
• render.yaml (Render Blueprint: API, Frontend, Redis)
• .github/workflows/cicd.yml (CI checks + deploy hook triggers)

1. Create services with Render Blueprint

1. Push this repo to GitHub.
2. In Render: New + -> Blueprint -> select this repository.
3. Render will read render.yaml and create:
   • shithub-api
   • shithub-frontend
   • shithub-redis

2. Set required secrets in Render

Set these secret values on shithub-api:

• GROQ_API_KEY
• BUG_API_KEY
• JWT_SECRET_KEY (auto-generated by blueprint, can be replaced)

3. Verify service URLs

If you rename services, update:

• BASE_URL and BACKEND_ORIGIN
• FRONTEND_ORIGINS in render.yaml to match your real Render domains.

4. Enable GitHub Actions deploy hooks (optional but recommended)

The workflow .github/workflows/cicd.yml runs on PR/push:

• backend compile smoke checks
• backend + CLI tests via pytest
• frontend build + tests
• deploy hook trigger on main

Add GitHub repository secrets:

• RENDER_API_DEPLOY_HOOK
• RENDER_FRONTEND_DEPLOY_HOOK

You can get these deploy hook URLs from each Render service:
Service Settings -> Deploy Hook.

Authentication

1. Register: POST /auth/register/start (returns token + user)
2. Login: POST /auth/login/start (returns token + user)
3. Optional avatar: POST /auth/me/avatar (upload), DELETE /auth/me/avatar (remove)
4. Session info: GET /auth/me

Mutation endpoints are owner-protected: authenticated users can only mutate repositories in their own namespace.

Web Usage

1. Sign in and open / for the logged-in dashboard.
2. Use repository pages under /u/:owner/repositories.
3. Edit code in the Monaco-based editor tab (/repo/:owner/:name/editor) and Save & Commit.
4. Use editor AI helpers:
   • AI Autocomplete for insert-at-cursor code completion
   • AI Commit Message to generate commit subject from current file changes
   • Debug with BugAI to get fix suggestions for selected code
5. Queue AI jobs from:
   • Generate README
   • Build with sh*tAI
6. Track jobs/logs in /repo/:owner/:name/actions.
7. Use /bugai for coding Q&A with optional repository context.

CLI Usage

Install CLI:

pip install -e .

Common commands:

shithub create <owner> <name>
shithub list <owner>
shithub ai-readme <owner> <name>
shithub job <job_id>

Testing

We use pytest for backend API and CLI tests. Tests are located in the /tests folder and auto-run in CI. To run tests locally:

pip install pytest responses httpx
PYTHONPATH=. pytest tests/

API Reference (Canonical)

Method	Path	Purpose
POST	/auth/register/start	Register and sign in (single step)
POST	/auth/login/start	Login and sign in (single step)
GET	/auth/me	Current user payload
POST	/auth/me/avatar	Upload avatar
DELETE	/auth/me/avatar	Remove avatar
POST	/repos/{owner}/{name}	Create repo
DELETE	/repos/{owner}/{name}	Delete repo
GET	/repos/{owner}	List repos
GET	/repos/{owner}/{name}/dashboard	Repo dashboard
GET	/repos/{owner}/{name}/tree	Repo tree at optional path
GET	/repos/{owner}/{name}/blob	File blob content
PUT	/repos/{owner}/{name}/blob	Save file content (commit + push)
POST	/repos/{owner}/{name}/ai/readme	Queue README job
POST	/repos/{owner}/{name}/ai/build	Queue sh*tAI build job
GET	/repos/{owner}/{name}/jobs	Repository jobs
GET	/jobs/{job_id}	Job status
GET	/jobs/{job_id}/logs	Job logs
POST	/ai/bugai/ask	bugAI coding Q&A
POST	/ai/bugai/autocomplete	Editor AI autocomplete
POST	/ai/bugai/commit-message	AI commit message generation

Backward Compatibility (Deprecated Aliases)

• GET /repos/repos/{owner}/{name}/dashboard
• GET /jobs/repos/{owner}/{name}/jobs
• GET /jobs/jobs/{job_id}/logs

Use canonical routes for new integrations.

Verification Checklist

• Register and login with email/password in a single step.
• Upload/change/remove profile picture; verify navbar + profile avatar updates.
• Create repo, list repo, delete repo.
• Clone repo using Smart HTTP.
• Run Generate README and inspect logs.
• Run Build with sh*tAI and inspect logs.
• In editor tab, verify AI autocomplete inserts completion at cursor.
• In editor tab, verify AI commit message populates commit input and Save & Commit works.
• Open /bugai and ask coding questions with and without repo context.

Troubleshooting

• Jobs stuck in queued: ensure Redis + Celery worker are running.
• 401/403 on mutations: sign in and use your own owner namespace.
• Git clone/push errors: verify backend is running and Git is installed.
• Avatar upload fails: use supported image type and smaller file size.

Security Notes

• Do not commit secrets or private credentials.
• Keep local config files private.