Skip to content
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 29 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,37 @@
# GitLab Browser

A modern, self-hostable GitLab frontend that authenticates with a **Personal Access Token** — no OAuth, no user licenses required. Browse and manage your GitLab projects entirely from your own deployment.
A modern, self-hostable GitLab frontend that works with **public repositories out of the box** and optionally authenticates with a Personal Access Token — no OAuth, no user licenses required. Browse public projects without any account, or sign in with a PAT to access private repos and write actions.

[![CI](https://github.com/gauthamp10/glabrowser/actions/workflows/ci.yml/badge.svg)](https://github.com/gauthamp10/glabrowser/actions/workflows/ci.yml)
[![Security](https://github.com/gauthamp10/glabrowser/actions/workflows/security.yml/badge.svg)](https://github.com/gauthamp10/glabrowser/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)](Dockerfile)
[![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=white)](https://react.dev)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
[![Live Demo](https://img.shields.io/badge/Live%20Demo-DigitalOcean-0080FF?logo=digitalocean&logoColor=white)](https://glabrowser-f3lru.ondigitalocean.app/)

> **🌐 Live demo:** [https://glabrowser-f3lru.ondigitalocean.app/](https://glabrowser-f3lru.ondigitalocean.app/) — browse public GitLab repositories instantly.

> **Note**: This project is not affiliated with or endorsed by GitLab Inc. It uses the public [GitLab REST API](https://docs.gitlab.com/api/rest/).

---

## Screenshots

| Login | Dashboard |
|-------|-----------|
| ![Login](docs/screenshots/login.png) | ![Repository](docs/screenshots/repository.png) |

| Git Graph | Merge Requests |
|-----------|----------------|
| ![Git Graph](docs/screenshots/git-graph.png) | ![Merge Requests](docs/screenshots/merge-request.png) |

| Pipelines | Insights |
|-----------|----------|
| ![Pipelines](docs/screenshots/pipeline.png) | ![Insights](docs/screenshots/insights.png) |

---

## Features

### Repository
Expand Down Expand Up @@ -60,13 +79,13 @@ cd glabrowser
docker compose up --build
```

Open **http://localhost:3000**, enter your GitLab instance URL and a Personal Access Token.
Open **http://localhost:3000**. You can browse public repositories immediately — no account needed. Optionally enter a Personal Access Token to access private repos and write actions.

### Docker (manual)

```bash
docker build -t glab-browser .
docker run -d -p 3000:80 --name glab-browser --restart unless-stopped glab-browser
docker build -t gitlab-browser .
docker run -d -p 3000:80 --name gitlab-browser --restart unless-stopped gitlab-browser
```

### Changing the port
Expand All @@ -92,6 +111,8 @@ npm install
npm run dev # starts at http://localhost:5173
```

Public repositories on gitlab.com are accessible immediately without any token.

```bash
npm run build # production build → dist/
npm run preview # preview the production build locally
Expand Down Expand Up @@ -126,6 +147,8 @@ Wrap the Docker container behind a reverse proxy (Nginx, Traefik, Caddy) that te

## Personal Access Token Scopes

A token is **optional** — public repositories on any GitLab instance are accessible without one. A PAT is required only for private repositories, write operations, and CI/CD features.

Create a token at `https://YOUR_GITLAB/-/user_settings/personal_access_tokens`

| Scope | Purpose | Required for |
Expand All @@ -142,14 +165,14 @@ Create a token at `https://YOUR_GITLAB/-/user_settings/personal_access_tokens`

**Quick-fill link:**
```
https://YOUR_GITLAB/-/user_settings/personal_access_tokens?name=glab-browser&scopes=read_api,read_repository,api
https://YOUR_GITLAB/-/user_settings/personal_access_tokens?name=gitlab-browser&scopes=read_api,read_repository,api
```

---

## Security

glab-browser is designed with a security-first approach to Personal Access Token handling and browser hardening.
GitLab Browser is designed with a security-first approach to Personal Access Token handling and browser hardening.

**Token protection**
- PATs are encrypted at rest using **AES-GCM-256 (WebCrypto)** — `localStorage` never contains a plaintext token
Expand Down
Binary file added docs/screenshots/git-graph.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screenshots/insights.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screenshots/login.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screenshots/merge-request.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screenshots/pipeline.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screenshots/repository.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 11 additions & 7 deletions src/__tests__/components/Login.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { MemoryRouter } from 'react-router-dom';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import Login from '../../pages/Login';
import { useAuthStore } from '../../store/auth';

Expand All @@ -19,10 +20,13 @@ vi.mock('react-router-dom', async (importOriginal) => {
});

function renderLogin() {
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
return render(
<MemoryRouter>
<Login />
</MemoryRouter>
<QueryClientProvider client={queryClient}>
<MemoryRouter>
<Login />
</MemoryRouter>
</QueryClientProvider>
);
}

Expand All @@ -43,7 +47,7 @@ describe('Login — initial render', () => {

it('renders host URL input with default https://gitlab.com', () => {
renderLogin();
const hostInput = screen.getByPlaceholderText('https://gitlab.com');
const hostInput = screen.getByLabelText('GitLab Host URL');
expect(hostInput).toHaveValue('https://gitlab.com');
});

Expand All @@ -66,7 +70,7 @@ describe('Login — insecure connection warning', () => {
it('shows warning when user types an http:// URL', async () => {
const user = userEvent.setup();
renderLogin();
const hostInput = screen.getByPlaceholderText('https://gitlab.com');
const hostInput = screen.getByLabelText('GitLab Host URL');
await user.clear(hostInput);
await user.type(hostInput, 'http://internal.corp');
expect(screen.getByText(/Insecure connection/i)).toBeInTheDocument();
Expand All @@ -75,7 +79,7 @@ describe('Login — insecure connection warning', () => {
it('does NOT show warning for https:// URLs', async () => {
const user = userEvent.setup();
renderLogin();
const hostInput = screen.getByPlaceholderText('https://gitlab.com');
const hostInput = screen.getByLabelText('GitLab Host URL');
await user.clear(hostInput);
await user.type(hostInput, 'https://gitlab.com');
expect(screen.queryByText(/Insecure connection/i)).not.toBeInTheDocument();
Expand All @@ -84,7 +88,7 @@ describe('Login — insecure connection warning', () => {
it('clears warning when user switches back to https://', async () => {
const user = userEvent.setup();
renderLogin();
const hostInput = screen.getByPlaceholderText('https://gitlab.com');
const hostInput = screen.getByLabelText('GitLab Host URL');
await user.clear(hostInput);
await user.type(hostInput, 'http://internal.corp');
expect(screen.getByText(/Insecure connection/i)).toBeInTheDocument();
Expand Down
21 changes: 14 additions & 7 deletions src/api/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ export class ApiError extends Error {

export interface ApiConfig {
host: string;
token: string;
token: string | null;
}

export type RequestParams = Record<string, string | number | boolean | undefined | null>;
Expand Down Expand Up @@ -59,16 +59,24 @@ export interface PagedResult<T> {
export function createApiClient(config: ApiConfig) {
const base = `${config.host.replace(/\/$/, '')}/api/v4`;

// Only attach the PRIVATE-TOKEN header when a token is configured.
// Omitting it allows the client to reach public GitLab API endpoints
// without any authentication (guest mode).
function authHeaders(extra: Record<string, string> = {}): Record<string, string> {
return config.token
? { 'PRIVATE-TOKEN': config.token, ...extra }
: extra;
}

async function request<T>(path: string, options: RequestOptions = {}): Promise<T> {
const { params, headers = {}, ...init } = options;
const url = buildUrl(base, path, params);

const res = await fetch(url, {
...init,
headers: {
'PRIVATE-TOKEN': config.token,
'Content-Type': 'application/json',
...headers,
...authHeaders(headers),
},
});

Expand All @@ -92,9 +100,8 @@ export function createApiClient(config: ApiConfig) {
const res = await fetch(url, {
...init,
headers: {
'PRIVATE-TOKEN': config.token,
'Content-Type': 'application/json',
...headers,
...authHeaders(headers),
},
});

Expand Down Expand Up @@ -137,7 +144,7 @@ export function createApiClient(config: ApiConfig) {

const res = await fetch(url, {
...init,
headers: { 'PRIVATE-TOKEN': config.token, ...headers },
headers: authHeaders(headers),
});

if (!res.ok) throw new ApiError(res.status, `HTTP ${res.status}`);
Expand All @@ -147,7 +154,7 @@ export function createApiClient(config: ApiConfig) {
async function fetchBlob(path: string, params?: RequestParams): Promise<Blob> {
const url = buildUrl(base, path, params);
const res = await fetch(url, {
headers: { 'PRIVATE-TOKEN': config.token },
headers: authHeaders(),
});
if (!res.ok) throw new ApiError(res.status, `HTTP ${res.status}`);
return res.blob();
Expand Down
7 changes: 5 additions & 2 deletions src/api/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import { useAuthStore } from '../store/auth';

export type GitLabApi = ReturnType<typeof createAllApis>;

function createAllApis(host: string, token: string) {
function createAllApis(host: string, token: string | null) {
const client = createApiClient({ host, token });
return {
client,
Expand All @@ -37,7 +37,10 @@ export function ApiProvider({ children }: { children: ReactNode }) {
const { token, host } = useAuthStore();

const api = useMemo(() => {
if (!token || !host) return null;
// token === null means "not set up yet" → no API client
// token === '' means guest mode → create client without a PAT (public access)
// token === 'glpat-...' means authenticated → create client with PAT
if (token === null || !host) return null;
return createAllApis(host, token);
}, [token, host]);

Expand Down
45 changes: 44 additions & 1 deletion src/api/repository.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import type { GitLabApiClient } from './client';
import type { GitLabTreeItem, GitLabFile, GitLabBlame, GitLabBranch } from '../types/gitlab';
import type { GitLabTreeItem, GitLabFile, GitLabBlame, GitLabBranch, GitLabFileOperation } from '../types/gitlab';

export function createRepositoryApi(client: GitLabApiClient) {
return {
Expand Down Expand Up @@ -85,5 +85,48 @@ export function createRepositoryApi(client: GitLabApiClient) {
{ method: 'DELETE' }
),

// Creates a new file in the repository. `content` must already be
// base64-encoded; pass encoding: 'base64'.
createFile: (
projectId: number,
filePath: string,
params: {
branch: string;
content: string;
commit_message: string;
encoding?: 'base64' | 'text';
author_name?: string;
author_email?: string;
}
) => {
const encodedPath = filePath.split('/').map(encodeURIComponent).join('%2F');
return client.request<GitLabFileOperation>(
`/projects/${projectId}/repository/files/${encodedPath}`,
{ method: 'POST', body: JSON.stringify({ encoding: 'base64', ...params }) }
);
},

// Updates an existing file in the repository. `content` must already be
// base64-encoded; pass encoding: 'base64'.
updateFile: (
projectId: number,
filePath: string,
params: {
branch: string;
content: string;
commit_message: string;
last_commit_id?: string;
encoding?: 'base64' | 'text';
author_name?: string;
author_email?: string;
}
) => {
const encodedPath = filePath.split('/').map(encodeURIComponent).join('%2F');
return client.request<GitLabFileOperation>(
`/projects/${projectId}/repository/files/${encodedPath}`,
{ method: 'PUT', body: JSON.stringify({ encoding: 'base64', ...params }) }
);
},

};
}
5 changes: 4 additions & 1 deletion src/components/PrivateRoute.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ import { useAuthStore } from '../store/auth';

export default function PrivateRoute() {
const { token } = useAuthStore();
if (!token) return <Navigate to="/login" replace />;
// token === null → user has never set up the app → redirect to login
// token === '' → guest mode (no PAT, public repos only) → allow through
// token === 'glpat-...' → authenticated → allow through
if (token === null) return <Navigate to="/login" replace />;
return <Outlet />;
}
23 changes: 22 additions & 1 deletion src/components/layout/AppLayout.tsx
Original file line number Diff line number Diff line change
@@ -1,18 +1,39 @@
import { Outlet } from 'react-router-dom';
import { Outlet, useNavigate } from 'react-router-dom';
import { LogIn } from 'lucide-react';
import Sidebar from './Sidebar';
import Topbar from './Topbar';
import { useKeyboardShortcuts } from '../../hooks/useKeyboardShortcuts';
import { TooltipProvider } from '../ui/tooltip';
import { useAuthStore } from '../../store/auth';

export default function AppLayout() {
useKeyboardShortcuts();
const { token } = useAuthStore();
const navigate = useNavigate();
const isGuest = token === '';

return (
<TooltipProvider>
<div className="flex h-screen overflow-hidden bg-background">
<Sidebar />
<div className="flex flex-col flex-1 min-w-0 overflow-hidden">
<Topbar />
{isGuest && (
<div className="flex items-center justify-between gap-3 px-4 py-2 bg-amber-500/10 border-b border-amber-500/20 text-amber-700 dark:text-amber-400 text-xs shrink-0">
<span>
<strong>Guest mode</strong> — you're browsing public repositories only.
Private repos, write actions, and CI/CD features require a token.
</span>
<button
type="button"
onClick={() => navigate('/login')}
className="flex items-center gap-1 font-medium underline underline-offset-2 hover:opacity-80 whitespace-nowrap"
>
<LogIn className="h-3 w-3" />
Sign in
</button>
</div>
)}
<main className="flex-1 overflow-auto">
<Outlet />
</main>
Expand Down
7 changes: 6 additions & 1 deletion src/components/layout/Sidebar.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import {
ChevronLeft, ChevronRight, Search, Pin, LogOut,
Plus, Server
} from 'lucide-react';
import { useQueryClient } from '@tanstack/react-query';
import { Button } from '../ui/button';
import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip';
import { Separator } from '../ui/separator';
Expand All @@ -22,11 +23,15 @@ const navItems = [
export default function Sidebar() {
const location = useLocation();
const navigate = useNavigate();
const queryClient = useQueryClient();
const { user, logout, instances, host, switchInstance } = useAuthStore();
const { sidebarCollapsed, toggleSidebar, pinnedProjects } = useSettingsStore();

const handleLogout = () => {
logout();
// Clear the entire query cache so no previous user's data leaks into
// the next session (guest or a different authenticated account).
queryClient.clear();
navigate('/login');
};

Expand Down Expand Up @@ -135,7 +140,7 @@ export default function Sidebar() {
{instances.map((instance) => (
<button
key={instance.host}
onClick={() => switchInstance(instance.host)}
onClick={() => { queryClient.clear(); switchInstance(instance.host); }}
className={cn(
'w-full flex items-center gap-2 px-2 py-1 rounded-md text-xs transition-colors',
instance.host === host
Expand Down
Loading
Loading