Git City: turning a GitHub profile into a 3D pixel art building

The problem Git City solves, and who it is actually for

A GitHub profile page is a list. Repositories, a contribution graph, a follower count, and nothing that conveys scale at a glance. Git City takes the same public signals and encodes them spatially: each user becomes a building, and the city is browsable in three dimensions. The README frames the pitch directly, describing the project as transforming "every GitHub profile into a unique pixel art building" where "the more you contribute, the taller your building grows."

The audience is narrower than the tagline suggests. This is not a tool for evaluating candidates or auditing a codebase. It is a visualization and a piece of social software: there are kudos, item gifting, referrals, a live activity feed and a shop. Developers who enjoy the aesthetic will use it to show off a profile, and teams running a community or a conference might use the compare mode to put two developers side by side. Anyone looking for analytics should look elsewhere, because the mapping from contribution history to geometry is deliberately coarse.

How a contribution count becomes building geometry

The README publishes the mapping as a small table, and it is the clearest specification in the repository. Contributions drive height, public repos drive width, stars drive window brightness, and recent activity drives the window pattern. Four inputs, four visual channels, no overlap between them.

Rendering is where the engineering sits. The README states that buildings are drawn with instanced meshes and a level-of-detail system: nearby buildings get full geometry with animated windows, distant ones fall back to simplified shapes. That is a sensible response to the obvious problem with a city of thousands of buildings, since a naive scene graph with one mesh per user would not survive contact with a real dataset. The stack is Next.js 16 with the App Router and Turbopack, Three.js through @react-three/fiber and drei, Supabase for Postgres, GitHub OAuth and Row Level Security, Stripe for payments, and Vercel for hosting. Row Level Security matters here: it means the database, not the client, is the enforcement point for who can read and write what.

The repository layout tells you the rest. There is a partykit.json at the top level alongside a party/ directory, and .env.example defines NEXT_PUBLIC_PARTYKIT_HOST with a comment describing it as the "PartyKit host (multiplayer arcade)". So the arcade is a separate realtime service, not part of the Next.js process, and it defaults to localhost:1999 in development.

Installing Git City and getting a city on screen

The README gives a plain clone-and-install path. The dev script pins port 3001 and forces webpack, so the URL you open is not the Next.js default.

git clone https://github.com/srizzon/git-city.git
cd git-city
npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3001 and the city renders. On Linux or macOS the copy command works as written; the README also lists a Windows Command Prompt variant using copy and a PowerShell variant using Copy-Item.

The more interesting path avoids Supabase entirely. The README states you can run the whole backend locally with no Supabase account and no GitHub OAuth app, provided you have a container runtime and the Supabase CLI.

brew install colima docker supabase/tap/supabase
colima start
supabase start
supabase status

The first supabase start pulls images and applies every migration from scratch, then prints your local URL and keys. supabase status reprints them at any time. Point .env.local at the printed values:

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<Publishable key from `supabase status`>
SUPABASE_SERVICE_ROLE_KEY=<Secret key from `supabase status`>

Because GitHub OAuth is not configured for a local stack, the README says clicking Sign in with GitHub locally routes you to a built-in dev login where you type any GitHub username and get a building from that account. You can also go straight to http://localhost:3001/api/dev/login. The README states this route is automatically disabled in production. Supabase Studio runs at http://127.0.0.1:54323 if you want to inspect the database directly.

For a real deployment you need values the local path does not supply. The README points to Supabase under Project Settings then API for NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY and SUPABASE_SERVICE_ROLE_KEY. GITHUB_TOKEN comes from GitHub under Settings, then Developer settings, then Personal access tokens, with fine-grained tokens recommended if you want to grant only the minimum profile and repository access. ADMIN_GITHUB_LOGINS is a comma-separated list that gates /admin/ads, and .env.example adds NEXT_PUBLIC_ADMIN_GITHUB_LOGINS, noting that the client copy only hides the in-game arcade Editor button while server enforcement still uses the non-public variable.

Where the local setup stops and the real deployment begins

The local Supabase path is genuinely convenient, and the README is honest about its boundary: the GitHub OAuth provider is not configured for a local stack because it needs a client secret that cannot ship in the repository. That is a reasonable call, but it means local development never exercises the real login flow. You are testing against a dev route, and the first time you find out whether your OAuth callback configuration is correct is in a deployed environment.

The environment file has a similar shape. Several variables exist only to point at storage buckets: NEXT_PUBLIC_COZY_BASE_URL for arcade assets and NEXT_PUBLIC_MODELS_BASE_URL for cosmetic GLB models, both left empty in local dev so files are served from /public. In production they point at Supabase Storage public URLs. The .env.example comment states that models are uploaded with scripts/upload-cosmetic-models.mjs, and that the script is kept out of git. So a deployment involves an upload step whose tooling is not in the repository, and the README does not describe what happens when a model is missing. There is also ARCADE_ADMIN_KEY, described as a bearer token for the admin POST invalidate endpoint at /api/arcade/rooms/[slug], and Stripe variables marked optional and only needed for payments.

None of this is disqualifying, but it means Git City is a full application to operate rather than a widget to drop in. You are running Next.js, Postgres, an auth provider, storage buckets and a separate realtime service.

The AGPL-3.0 boundary and what it costs to upgrade

The licence is AGPL-3.0, and the README states the consequence plainly: you can use and modify Git City, but any public deployment must share the source code. For a personal instance or an internal tool this is unremarkable. For a company that wants to run a branded city as a marketing surface, the network copyleft obligation is the first thing to resolve, and the LICENSE file is the document to read rather than a summary. This is a description of the licence text, not legal advice.

Upgrade cost is the weaker side. The repository has no releases, package.json declares version 0.1.0, and the material describes no migration or upgrade procedure. There is a supabase db reset command and a db:reset npm script, both of which re-apply all migrations on a clean database, which is useful in development and destructive by definition. Nothing in the README covers applying new migrations to a database that already holds user data. Combined with a Next.js 16 / React Three Fiber 9 dependency set, the practical upgrade path is to track the main branch and read the migrations directory before pulling. The last push to the repository was on 2026-09-04, so the code is recent, but recency is not the same as a supported release channel.

Git City compared with GitHub Skyline

GitHub Skyline is the closest reference point people reach for, and the difference is structural rather than cosmetic. Skyline renders one user's contribution year as a single extruded skyline, a personal artefact you generate and download. Git City renders many users into one shared, navigable space, which is why it needs a database, authentication, a level-of-detail system and a realtime arcade service.

That difference decides the use case. If you want a personal year-in-review image, Skyline is the smaller and more direct answer. If you want a place where profiles coexist and can be compared, customized and visited, Git City is doing something Skyline was never designed to do. The cost of that ambition is everything in the previous section: a backend, storage buckets, and a deployment you maintain yourself.

Editorial conclusion

Adopt Git City if you want a self-hosted, visually distinctive way to browse developer profiles and you are comfortable running Next.js, Supabase and a container runtime locally. Do not adopt it if you need a stable release artefact or a documented upgrade path: the repository has no releases, the package version is 0.1.0, and tracking main is the only upgrade story the material describes. Before deploying publicly, verify your AGPL-3.0 obligations with the LICENSE file, confirm which Supabase keys your deployment exposes, and check that the dev login route at /api/dev/login is disabled in production as the README states.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Project website
4. README
5. srizzon/git-city on GitHub