gits

A personal Git repository host built on Cloudflare Workers, focused on Git storage, repository management, and code browsing.

• Git hosting — Smart HTTP clone, fetch, and push, with shallow clone and object filters. Each repository stores Git objects and refs in its Durable Object SQLite database; packs stream in and out without loading the entire repository. R2 is used only to import legacy repositories.
• GitHub sync — Install a GitHub App to mirror personal or organization repositories, with Webhook updates. Mirrors are read-only until you stop synchronization.
• Authentication — Register, login, logout, revocable server-side sessions and login device management, and Personal Access Tokens (PAT). Git Basic Auth uses a username and PAT.
• Repositories — Create, rename, update visibility and description, delete, and manage collaborators with read / write / admin permissions.
• Branches — Owners can create and delete branches and set the default branch through the web UI or API.
• Code browsing — README, directory trees, text files, paginated commits, commit details with diffs, and path history.

Repositories belong to individuals. Git access is HTTP only and file browsing is read-only. GitHub organization repositories can sync into a personal namespace. Issues, pull requests, CI, SSH, Git LFS, code search, and branch protection are out of scope; see the scope definition.

Repository data is read on demand; clone and push stream pack data. Full object resolution is limited to 32 MiB, while previews of full objects read only a prefix. Storage remains subject to the SQLite Durable Object capacity limit of 10 GB per repository, and request CPU time is configured to 300,000 ms.

Use Node.js 22.12+ with npm and Git.

npm install
npm --prefix web install
cp .env.example .env
npm run build:web
npm run dev

npm run dev applies local D1 migrations and starts the Worker with .env. The initial build supplies the static assets configured in wrangler.jsonc.

In another terminal:

npm run dev:web

Open the URL printed by Vite. Its proxy sends API, health, and Git requests to http://127.0.0.1:8787; keep the Worker on that port for this setup.

The local .env template contains:

ALLOW_USER_REGISTRATION=true

Local .env values are loaded by the development script. Configure production variables separately. Login sessions do not require a signing secret. All six GitHub App settings are required to enable synchronization.

Create separate production and Preview resources:

npx wrangler login
# Production
npm run d1:create:remote
npx wrangler r2 bucket create gits
# Previews
npx wrangler d1 create gits-preview
npx wrangler r2 bucket create gits-preview

Copy the returned production D1 ID into wrangler.jsonc → d1_databases[0].database_id. Copy the Preview D1 ID into both wrangler.jsonc → previews.d1_databases[0].database_id and wrangler.preview-migrations.jsonc → d1_databases[0].database_id; both Preview entries must point at the same database.

Login uses random, server-side sessions stored in D1. When upgrading, apply all pending migrations before deploying the new Worker (the deploy scripts do this automatically). Existing JWT sessions are invalidated; users must log in again. Existing PATs remain valid. JWT_SECRET is no longer used. GitHub App authentication still uses GitHub's required App JWTs.

Connect this repository to the gits Worker in Workers Builds, select the production branch, and enable Preview builds for all other branches. Use the repository root and these commands:

Worker Previews require the project's Wrangler dependency to be at least 4.135.0; a global installation is not used. Preview URLs use <branch>-gits.<subdomain>.workers.dev.

npm run preview first migrates the preview D1 database using wrangler.preview-migrations.jsonc, then runs wrangler preview. All branches share the preview D1/R2 resources, isolated from production; DO storage is separate per Preview. The previews block explicitly sets DB, GIT_BUCKET, REPOSITORY_OBJECTS, and ALLOW_USER_REGISTRATION="true" because production settings are not inherited. Assets, compatibility settings, and DO migrations remain top-level. See Cloudflare Preview configuration.

Production Cron checks for due discovery and mirror tasks every five minutes. Webhooks trigger updates immediately; a full discovery every six hours provides a fallback. Worker Previews do not support GitHub synchronization: the App has one Webhook and Setup URL pointing at production. Do not configure App secrets or Cron under previews.

npm run deploy -- --var ALLOW_USER_REGISTRATION:true

The script applies remote D1 migrations, builds the frontend, then deploys the Worker with --keep-vars. For later deployments with existing production variables:

npm run deploy

To close registration, set the production registration variable to any value other than true, or remove it. Check GET /healthz or GET /api/healthz after deployment.

npm run db:migrate:local
npm run db:migrate
npm run db:migrate:preview

These target local D1, production D1, and preview D1 respectively.

gits/
├── src/
│   ├── routes/api/         # Auth, repository management and browsing
│   ├── routes/git.ts       # Smart HTTP endpoints
│   ├── services/           # Git, storage, repository state and auth
│   ├── middleware/         # Auth and error handling
│   └── db/migrations/      # D1 migrations
├── web/
│   └── src/
│       ├── pages/          # React route pages
│       ├── components/     # UI components
│       └── lib/            # API client and utilities
├── scripts/                # Local secret configuration
├── prd/                    # Product requirements
├── docs/                   # Usage guide
└── wrangler.jsonc          # Worker configuration

• GET /healthz, GET /api/healthz — Health checks
• POST /api/auth/register, POST /api/auth/login, POST /api/auth/logout — Account access
• GET /api/me — Current user
• POST /api/auth/tokens, GET /api/auth/tokens — Create and list PATs
• DELETE /api/auth/tokens/:tokenId — Revoke a PAT
• GET /api/auth/sessions?page=1 — List active login devices, 20 per page
• DELETE /api/auth/sessions/:sessionId — Revoke another login session
• DELETE /api/auth/sessions — Revoke every other session, keeping the current one

API authentication accepts the login cookie or Bearer session tokens/PATs. Public repository reads do not require authentication. Sessions expire after seven days. Logout revokes the server-side session. Manage devices at /sessions; revoking a device blocks subsequent requests using its token. Device management requires a login session, not a PAT. API responses are not cached, and cross-origin mutations are rejected. Browser/OS labels come from User-Agent and identify login sessions, not physical devices.

• GET /api/public/repos — Public repositories (limit)
• GET /api/repos, POST /api/repos — List accessible repositories / create a repository
• GET /api/repos/:owner/:repo — Repository detail (ref), including the viewer's viewerPermission
• PATCH /api/repos/:owner/:repo, DELETE /api/repos/:owner/:repo — Update / delete, owner only
• GET /api/repos/:owner/:repo/collaborators, PUT /api/repos/:owner/:repo/collaborators — List / add or update collaborators
• DELETE /api/repos/:owner/:repo/collaborators/:username — Remove a collaborator

Collaborator management requires the owner or an admin collaborator. Repository settings and deletion require the owner.

• GET /api/repos/:owner/:repo/branches — List branches
• POST /api/repos/:owner/:repo/branches — Create from branchName and an existing commit sourceOid, owner only
• PATCH /api/repos/:owner/:repo/default-branch — Set branchName as default, owner only
• DELETE /api/repos/:owner/:repo/branches/:branch — Delete a non-default branch, owner only; URL-encode the branch name
• GET /api/repos/:owner/:repo/contents — Directory or file (ref, path)
• GET /api/repos/:owner/:repo/commits — Commit history (ref, page, limit)
• GET /api/repos/:owner/:repo/commits/:oid — Commit detail
• GET /api/repos/:owner/:repo/history — Path history (required path, optional ref, limit)

Register an App for this instance:

npm run github-app:create -- --url https://git.example.com --target prod
# For a development instance with its own publicly reachable callback and Webhook URL:
npm run github-app:create -- --url https://dev-git.example.com --target dev
# Add --org <organization> to register the App under an organization.

The command opens a local registration page, completes GitHub's App Manifest flow and saves all six credentials. prod uses Wrangler secret prompts via stdin; dev updates .env, with the private key encoded as one base64 line. Secret values are not printed. The registrar's loopback callback is temporary; the App's OAuth callback, Setup URL and Webhook target the instance. Add --no-open to open the printed registration URL in a browser of your choice. The suggested App name is capped at GitHub's 34-character limit and can be edited on the registration page.

For manual registration, choose Any account (public installation) and configure:

Set each of the six GITHUB_APP_* secrets listed above using npx wrangler secret put <NAME> (or the corresponding local .env value). Private keys can be GitHub's PKCS#1 PEM or PKCS#8 PEM, including base64-encoded PEM. Worker Previews are not supported.

Users select Add account or organization, install the App on GitHub, choose all or selected repositories, and return to gits for automatic binding. Link existing installation starts OAuth directly. Only the account owner can bind a personal installation; organizations require an active organization administrator. Each installation belongs to one gits user. Repeat binding refreshes account metadata without resetting sync settings. Repository selection stays on GitHub.

Signed Webhooks request synchronization, while six-hour discovery recovers missed events. User access tokens are never stored; installation access tokens remain only in memory and refresh five minutes before expiry. Unbinding preserves local repositories and restores writes without uninstalling the App. Uninstalling on GitHub also unbinds automatically.

JSON endpoints require login and return only the current user's sources. Times are milliseconds. OAuth returns bound=<count> and repeated skipped=<login>:<reason> (not_owner, not_admin, taken); failures return error=state|denied|github|not_configured|pending_approval. Repository details include mirror (or null); lists include is_mirror (0 or 1). Mirrors reject push with 403 and reject branch or metadata edits with 409; renaming is allowed.

• GET /:owner/:repo.git/info/refs?service=git-upload-pack — Read reference discovery
• GET /:owner/:repo.git/info/refs?service=git-receive-pack — Write reference discovery
• POST /:owner/:repo.git/git-upload-pack — Fetch
• POST /:owner/:repo.git/git-receive-pack — Push

The .git suffix is optional. Push requires Basic Auth with a PAT and repository write permission.

• Product requirements
• 中文使用文档

Private