This file is intended for AI agents (Cursor, Copilot, Claude, etc.) picking up development of this project. Read it fully before making any changes.
A full-featured GitLab frontend web app that authenticates via Personal Access Token (PAT) — no individual GitLab license required. Built because teams were handing out PATs + glab CLI just so members could browse repos and check pipelines.
- Live demo: https://glabrowser-bchpz.ondigitalocean.app/
- GitHub: https://github.com/gauthamp10/gitlab-browser
- Branch:
feature/base(all development happens here, notmain)
| Layer | Choice |
|---|---|
| Framework | React 18 + TypeScript + Vite 8 |
| Routing | React Router v7 |
| Data fetching | TanStack Query v5 |
| State | Zustand v5 with persistence |
| UI | shadcn/ui (Radix primitives) + Tailwind CSS v4 |
| Syntax highlighting | Shiki v1 (lazy-loaded per language) |
| Icons | Lucide React |
| Dates | date-fns v3 |
| ANSI logs | ansi-to-html (escapeXML: true) |
| Testing | Vitest + jsdom + @testing-library/react |
| Deployment | Docker multi-stage (node:20-alpine → nginx:alpine) |
src/
api/ # GitLab REST API v4 client modules (one file per resource)
components/ # Reusable UI components
layout/ # AppLayout, Sidebar, Topbar, ProjectLayout
common/ # EmptyState, ErrorMessage, PermGate, ContributionHeatmap …
repository/ # UploadFileDialog, InlineEditor, CreateBranchDialog
pipelines/ # JobLog, PipelineStatus
mergeRequests/ # CreateMRDialog
projects/ # CreateProjectDialog
ui/ # shadcn/ui primitives (do not edit manually)
pages/ # Route-level page components
project/ # All per-project pages (Repository, Issues, MRs, Pipelines …)
store/ # Zustand stores (auth.ts, settings.ts)
hooks/ # Custom React hooks
utils/ # Pure utilities (crypto, url, safeHref, gitGraph, format)
types/ # gitlab.ts — all GitLab API response types
test/ # Vitest setup file
__tests__/ # Test suites (mirrors src/ structure)
!token(nullor'') → not logged in → redirect to/logintoken === 'glpat-...'→ authenticated
There is no guest/unauthenticated mode (removed in Iteration 15).
PATs are encrypted in localStorage using WebCrypto AES-GCM-256 (src/utils/crypto.ts). The session key lives in sessionStorage and is regenerated each browser session.
The ApiProvider (src/api/index.ts) only creates the API client when a token is set. PrivateRoute (src/components/PrivateRoute.tsx) redirects to /login when !token.
src/api/client.ts — createApiClient({ host, token }) returns a typed client with:
request<T>()— single resourcerequestPaged<T>()— paginated, returns{ items, pagination }requestText()— raw text (file content)fetchBlob()— binary download viaURL.createObjectURL()
ApiError (exported from client.ts) carries a numeric status property. Always use err instanceof ApiError + err.status for error handling — never render err.message directly into the DOM (CodeQL taint violation).
All API modules live in src/api/ and are aggregated in src/api/index.ts.
These were the result of a full security audit. Do not regress them.
- Never put
err.messagefrom API responses into React state/DOM. Useerr.status(a number) to select a hardcoded string instead. - Never interpolate the
hostinput into href attributes. Usenew URL(host).origin(URL-parser output) for links. safeExternalHref(url)(src/utils/safeHref.ts) — use for any API-sourced URL going intohreforimg src.- PAT must never appear in URL query strings. Always use the
PRIVATE-TOKENheader. File downloads usefetchBlob()+URL.createObjectURL(). - CSP, HSTS, X-Frame-Options are set in
nginx-vhost.conf. Do not weaken them. nginx.confruns nginx as non-root, uses/tmpfor pid/temp files.
Security implementation details: SECURITY.md
src/hooks/useTokenPermissions.ts — detects PAT scopes by probing the API.
src/components/common/PermGate.tsx — wraps UI elements, disabling/greying them when the token lacks the required scope. Use <PermGate scope="write_repository"> pattern.
The browser only lists groups/projects the token's user is a member of. Public projects outside those memberships are never listed.
api.projects.list()always forcesmembership: true.api.groups.list()defaultsmin_access_level: 10(Guest) — without it GitLab also returns all public groups (or every group for admins).- Search: Projects scope uses
api.projects.list({ search }). Other scopes call global/searchand filter results toapi.projects.listMemberIds(). - Do not add listing calls that bypass these (e.g. raw
/projectswithoutmembership). - Sidebar:
queryClient.clear()is called on logout and instance switch to prevent cache bleed between sessions.
# Run all tests in Docker (recommended)
docker run --rm -v $(pwd):/app -w /app node:20-alpine \
sh -c "node_modules/.bin/vitest run --reporter=verbose"
# TypeScript check + production build
docker run --rm -v $(pwd):/app -w /app node:20-alpine \
sh -c "node_modules/.bin/tsc --noEmit && node_modules/.bin/vite build"130 tests across 8 test files. Always run tests before pushing. All must pass.
Test files:
src/__tests__/utils/url.test.ts— 33 testssrc/__tests__/utils/crypto.test.ts— 16 testssrc/__tests__/security/safeHref.test.ts— 15 testssrc/__tests__/api/client.test.ts— 19 testssrc/__tests__/store/auth.test.ts— 12 testssrc/__tests__/components/JobLog.test.tsx— 10 testssrc/__tests__/components/Login.test.tsx— 12 testssrc/__tests__/utils/pipelineStages.test.ts— 13 tests
# Run the app locally
docker compose up --build
# App is served at http://localhost:3000Dependencies are installed inside the Docker build — no local Node.js needed.
Workflows in .github/workflows/:
| File | What it does |
|---|---|
ci.yml |
TypeScript check, ESLint, Vitest (130 tests) |
security.yml |
npm audit, gitleaks secret scan, dependency review |
codeql.yml |
CodeQL static analysis (JavaScript/TypeScript) |
release.yml |
Builds and pushes Docker image on tag |
All checks must be green before merging. Use [skip ci] in commit message only for docs-only changes (e.g. README URL updates).
nginx.confuser directive warning — nginx logs a warning about theuserdirective being ignored (non-root). This is harmless and expected.node_modules/.bin/vitestspawn error — vitest cannot run directly on this host (no Node.js installed locally). Always use Docker for tests.- Chunk size warnings — Vite warns about large chunks (Shiki language packs). These are expected and not errors. Consider code-splitting if bundle size becomes a concern.
package-lock.json— the Docker build copies the lockfile and runsnpm ci --legacy-peer-deps, so the image matches the audited dependency tree.
- Add more test coverage for page-level components
- Code-split Shiki language packs to reduce initial bundle size
- Notifications / activity feed for authenticated users
- Dark/light theme toggle persistence per-instance
- Commit
package-lock.jsonsonpm cican be used in CI for reproducible builds - Merge
feature/baseintomainonce stable
- Scaffolded with Vite 5 + React 18 + TypeScript
- Set up shadcn/ui, Tailwind CSS, React Router v6, TanStack Query v5, Zustand v5
- Could not install Node.js locally (sandbox restriction) — switched entirely to Docker
- Dockerfile: multi-stage build (
node:20-alpinebuilder →nginx:alpinerunner) docker-compose.ymlwith port 3000 mapping- Core API client (
src/api/client.ts) with typedfetchwrapper,ApiError, pagination support - API modules created for: projects, issues, merge requests, pipelines, repository, users, groups, search, todos, wiki
- Auth store (Zustand) with
localStoragepersistence and multi-instance support - All GitLab types defined in
src/types/gitlab.ts
- Built all route-level pages: Dashboard, Projects, Groups, Search, Profile, Todos
- Built per-project pages: Repository browser, Issues, MRs, Pipelines, Commits, Compare, Overview, Settings, Wiki, Insights
AppLayoutwith Sidebar and TopbarProjectLayoutwith per-project tab navigationPrivateRouteguard redirecting unauthenticated users to/login- Contribution heatmap on Dashboard
- Shiki v1 syntax highlighting (lazy-loaded per language) in
FileViewer - Custom diff renderer in
DiffViewer - PAT scope detection via
useTokenPermissionshook PermGatecomponent to grey out features the token lacks permission for (instead of hiding them)
Problem: Repository page loaded briefly then went blank on refresh.
Fix: Corrected Radix UI Select usage (SelectGroup/SelectLabel). Used useParams()['*'] for robust wildcard path extraction. Added error boundary in ProjectLayout.
Problem: Download source code was not working.
Fix: Implemented fetchBlob() method in API client. Used URL.createObjectURL() for downloads. Earlier attempt embedded token in URL query string — this was a vulnerability and was reverted.
Problem: Creating new project and merge requests redirected to GitLab.
Fix: Implemented projects.create API method and CreateProjectDialog component. Implemented CreateMRDialog component for in-app MR creation.
Problem: Pipeline view showed blank page.
Fix: <SelectItem value=""> caused Radix state to break — changed to value="all". Removed unused destructuring in PipelineDetail.
- Removed Issues, Wiki, Overview, To-do tabs from navigation (later Issues was re-added)
- Set Repository as default project tab
- Made recent activity and contribution map on Dashboard clickable/navigatable
- Fixed empty Recent Projects section on Dashboard
- Added ability to create branches from the UI (
CreateBranchDialog) - MR listing shows both open and closed MRs (status filter)
- Added Repository Settings page (
src/pages/project/Settings.tsx)
- Implemented custom SVG-based git graph algorithm in
src/utils/gitGraph.ts - Renders branch lanes, merge lines, commit nodes with colour-coded branches
- Accessible from the Commits page of any project
- No external graph library — fully custom to avoid large dependencies
Problem: DigitalOcean App Platform (Kaniko builder) failed: touch: /var/run/nginx.pid: No such file or directory
Fix (initial): Added mkdir -p /var/run in Dockerfile.
Fix (final, during security hardening): Moved nginx pid to /tmp/nginx.pid in nginx.conf — making the /var/run workaround unnecessary.
Problem: npm ci failed in Docker — no package-lock.json committed.
Fix: Changed Dockerfile to npm install --legacy-peer-deps.
Problem: TypeScript errors (TS2322) on asChild prop and RequestParams type.
Fix: Added @radix-ui/react-slot, implemented asChild support on Button. Broadened RequestParams type.
Full audit was performed. Issues found and fixed:
| Severity | Issue | Fix |
|---|---|---|
| Critical | PAT stored as plaintext in localStorage |
WebCrypto AES-GCM-256 encryption (src/utils/crypto.ts), session key in sessionStorage |
| Critical | File download embedded token in URL query string | Reverted to fetchBlob() + URL.createObjectURL() |
| High | No Content Security Policy | Added strict CSP in nginx-vhost.conf: script-src 'self', connect-src 'self' https:, object-src 'none' |
| High | CI job logs rendered raw HTML (ANSI parser) | Replaced custom parser with ansi-to-html library (escapeXML: true) |
| High | nginx running as root | Added non-root nginx user, moved pid/temp to /tmp in nginx.conf |
| High | javascript: URI injectable into href via host input |
Added safeExternalHref() utility, then later replaced with new URL(host).origin approach |
| High | err.message from API rendered into DOM |
Replaced with hardcoded strings keyed on numeric err.status |
| Medium | No HSTS, X-Frame-Options, Referrer-Policy headers | Added all to nginx-vhost.conf |
| Medium | Dev server bound to 0.0.0.0 |
Changed to localhost in vite.config.ts |
| Medium | Insecure GitLab host not warned | Added HTTP warning banner on Login page |
| Medium | SVG MIME type wrong (data:image/svg) |
Fixed to data:image/svg+xml |
| Medium | ref param not encoded in raw URL |
Added encodeURIComponent |
| Low | token exposed on API client object |
Removed from returned object |
Created SECURITY.md documenting all controls. Updated README to say "security enforced" rather than listing issues.
Added full Vitest test suite:
vitest.config.ts,src/test/setup.tssrc/__tests__/utils/crypto.test.ts— 16 tests for WebCrypto encrypt/decrypt/storagesrc/__tests__/utils/url.test.ts— 33 tests for URL utilitiessrc/__tests__/security/safeHref.test.ts— 15 tests forsafeExternalHrefsrc/__tests__/api/client.test.ts— 19 tests for API client (headers, errors, pagination)src/__tests__/store/auth.test.ts— 12 tests for Zustand auth storesrc/__tests__/components/JobLog.test.tsx— 10 tests (ANSI rendering, XSS safety)src/__tests__/components/Login.test.tsx— 12 tests (render, insecure warning, submit, errors)
Fixes needed during test setup:
- Installed
@testing-library/dom(was missing) - Fixed
getFileExtension('.gitignore')expectation ('gitignore'not'') - Removed duplicate
logDivvariable inJobLog.test.tsx - Replaced unsupported CSS selector
script[type!="text/javascript"]withquerySelectorAll('script').length - Wrapped
LogininQueryClientProviderto supportuseQueryClient() - Removed
skype/linkedin/twitterfrommakeUserhelper (not inGitLabUsertype) - Fixed
Uint8Array<ArrayBufferLike>TypeScript error incrypto.tsby using explicitnew ArrayBuffer()
Created .github/workflows/:
ci.yml— TypeScript check (tsc --noEmit), ESLint, Vitestsecurity.yml—npm audit, gitleaks secret scan, GitHub dependency reviewcodeql.yml— CodeQL static analysis for JS/TSrelease.yml— Docker image build and push on semver tag
Fixed ESLint setup:
- Installed
eslint,@eslint/js,typescript-eslint,eslint-plugin-react-hooks,eslint-plugin-react-refresh - Created
eslint.config.js(ESLint 9 flat config format) - Disabled React Compiler rules (
purity,refs,set-state-in-effect) ineslint.config.jsas they are too strict without the React Compiler - Fixed
no-useless-escapeinCreateProjectDialog.tsx - Fixed
@typescript-eslint/no-unused-expressionsinCommits.tsx
UploadFileDialogcomponent (src/components/repository/UploadFileDialog.tsx): drag-and-drop or file picker, base64 encoding, commit message, branch selectionInlineEditorcomponent (src/components/repository/InlineEditor.tsx): textarea editor, commit message, branch selection, save/cancel- Added
createFile(POST) andupdateFile(PUT) tosrc/api/repository.ts - Integrated both into
Repository.tsx(upload button) andFileViewer.tsx(edit button, gated bycanWriteRepo)
Goal: Allow browsing public GitLab repos without requiring a PAT.
Changes:
auth.ts: addedbrowseAsGuest(host)action — setstoken: ''auth.ts: renamedlocalStoragekey fromglab-browser-authtogitlab-browser-authPrivateRoute.tsx: changedif (!token)toif (token === null)sotoken === ''passes throughapi/index.ts: changedif (!token || !host)toif (token === null || !host)so guest mode creates an API clientapi/client.ts:authHeaders()function omitsPRIVATE-TOKENheader when token is falsyLogin.tsx: added "Browse public repositories" card with host inputAppLayout.tsx: amber banner shown in guest mode with Sign in linkTopbar.tsx: shows "Sign in" button instead of avatar in guest modeDashboard.tsx:starredProjectsquery gated withenabled: !!user; contribution heatmap replaced with sign-in prompt in guest modeSidebar.tsx:queryClient.clear()called on logout and instance switch to prevent cache bleed
Bug: After signing out and signing in as guest, previous user's data was still shown.
Fix: Added queryClient.clear() to handleBrowseAsGuest in Login.tsx and handleLogout in Sidebar.tsx.
Bug: Guest mode search returned blank (global /search requires auth).
Fix: In Search.tsx, guest mode projects scope uses GET /projects?search=...&visibility=public. Other scopes disabled with lock icon. TypeScript error (TS2339) on union type fixed by annotating mapped items as : GitLabSearchResult.
- Added
useCursorBlobhook inLogin.tsx - Two blurred gradient blobs follow the cursor using
requestAnimationFrame+lerp - Primary blob: 8% lerp per frame; secondary blob: 40% of primary movement for depth
- Uses direct DOM style manipulation (not React state) for performance
- Cleaned up with
cancelAnimationFrameandremoveEventListeneron unmount
Round 1: safeExternalHref() added to validate href and img src attributes.
Round 2: Error message sanitisation — err.message.replace(/<[^>]*>/g, '') — but CodeQL flagged that /<[^>]*>/g doesn't match <script without closing >.
Round 3 (final): Complete elimination of taint paths:
createTokenHref— replacedsafeExternalHref(host + ...)withnew URL(normalizeHost(host)).origininsideuseMemo. URL-parser output is not tainted.- Error display — replaced all
err.messageusage with hardcoded strings keyed onerr.status(a number).ApiErroris checked first;TypeErrorcatches network failures; everything else gets a generic message. - Avatar
src— wrappedinstance.user.avatar_urlwithsafeExternalHref().
api.pipelines.getAllJobs/getAllBridges(paged, capped at 10 pages) andlistProjectJobssrc/utils/pipelineStages.ts: groups jobs + trigger jobs (bridges) into stages ordered by first job id (keeps custom.gitlab-ci.ymlstage order), composite stage statususePipelineStageshook polls only while the pipeline is active- Pipelines list: GitLab columns (Status / Pipeline / Created by / Stages);
MiniPipelineGraphshows a stage icon per stage with a job dropdown, plus downstream pipeline icons - Pipeline detail: tabs Pipeline / Jobs / Failed jobs / Downstream;
PipelineGraphrenders stage columns and a Downstream column whose cards expand inline (recursive) to show multi-project or child pipelines;?job=<id>deep-links the job log - Pipelines page has a project-wide Jobs tab (
?tab=jobs) usingJobsTable; job run/retry/cancel buttons are wired up
- Projects, Groups, Dashboard and Search only show groups/projects the token's user is a member of
- Removed the "Member projects" toggle on the Projects page (always on)
- Removed guest mode:
browseAsGuest, Login "Browse public repositories" card, guest banner and Topbar sign-in button
- README rewritten for public release: self-hosting instructions, Docker quickstart, feature list, screenshots section (6 screenshots), security section ("security enforced"), live demo badge, CI/CodeQL badges
- Renamed project from "glab-browser" to "gitlab-browser" throughout
- Added live demo URL:
https://glabrowser-bchpz.ondigitalocean.app/ - Created
SECURITY.mddocumenting all security controls - Created
AGENTS.md(this file) for AI agent handoff