Documentation

Prerequisites

• Node.js 20+
• npm
• A GitHub Personal Access Token (standalone mode) or a GitHub OAuth App (organization mode)

Quick Start — Standalone Mode

The fastest way to get running. No OAuth App needed.

git clone https://github.com/dinhdobathi1992/gitdash.git
cd gitdash
cp .env.local.example .env.local

# Edit .env.local:
#   MODE=standalone
#   SESSION_SECRET=$(openssl rand -hex 32)

npm install
npm run dev

Open http://localhost:3000 — you will be redirected to /setup to enter your PAT.

Quick Start — Organization Mode

For teams sharing a single deployment. Requires a GitHub OAuth App.

# 1. Create a GitHub OAuth App:
#    Settings → Developer settings → OAuth Apps → New OAuth App
#    Callback URL: http://localhost:3000/api/auth/callback

# 2. Configure .env.local
MODE=organization
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
SESSION_SECRET=$(openssl rand -hex 32)

# 3. Run
npm install && npm run dev

Required GitHub PAT Scopes

Docker — Standalone

docker run -d \
  --name gitdash \
  -p 3000:3000 \
  -e MODE=standalone \
  -e SESSION_SECRET=your_32_char_secret_here \
  --restart unless-stopped \
  dinhdobathi1992/gitdash:latest

Docker — Organization Mode

docker run -d \
  --name gitdash \
  -p 3000:3000 \
  -e MODE=organization \
  -e GITHUB_CLIENT_ID=your_client_id \
  -e GITHUB_CLIENT_SECRET=your_client_secret \
  -e SESSION_SECRET=your_32_char_secret_here \
  -e NEXT_PUBLIC_APP_URL=https://gitdash.example.com \
  --restart unless-stopped \
  dinhdobathi1992/gitdash:latest

Docker Compose

Create a docker-compose.yml alongside your .env.local:

services:
  gitdash:
    image: dinhdobathi1992/gitdash:latest
    ports:
      - "3000:3000"
    env_file:
      - .env.local
    restart: unless-stopped

docker compose up -d      # start
docker compose down       # stop
docker compose logs -f    # view logs

Vercel (One-click)

GitDash deploys to Vercel automatically on push to main. To deploy your own fork:

1. Fork the repository on GitHub
2. Import the fork in Vercel (New Project → Import Git Repository)
3. Add all required environment variables in Vercel's project settings
4. Set the Authorization callback URL in your GitHub OAuth App to https://your-vercel-url/api/auth/callback

Reverse Proxy / Custom Domain

1. Set NEXT_PUBLIC_APP_URL to your public URL (e.g. https://gitdash.example.com)
2. Update the OAuth App callback URL to match
3. Ensure your proxy forwards the x-forwarded-proto header — the app uses this to enforce HTTPS redirects

Environment Variables

Example .env.local — Standalone

MODE=standalone
SESSION_SECRET=replace_with_openssl_rand_hex_32_output
NEXT_PUBLIC_APP_URL=http://localhost:3000

Example .env.local — Organization

MODE=organization
GITHUB_CLIENT_ID=your_oauth_app_client_id
GITHUB_CLIENT_SECRET=your_oauth_app_client_secret
SESSION_SECRET=replace_with_openssl_rand_hex_32_output
DATABASE_URL=postgresql://user:pass@host/db?sslmode=require
NEXT_PUBLIC_APP_URL=https://gitdash.example.com

Creating a GitHub OAuth App

1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
2. Fill in the fields:

3. Click Register application, then copy the Client ID
4. Click Generate a new client secret and copy it immediately — it is shown only once

Standalone vs. Organization

Switching Modes

Change the MODE environment variable and restart the server. All session data is invalidated automatically — users will be redirected to the appropriate login page.

# Switch to org mode
MODE=organization

# Switch back to standalone
MODE=standalone   # or unset MODE entirely

Workflow Dashboard Tabs

Other Capabilities

• Job & step drill-down — expand any run row to see per-job and per-step timings
• Per-chart PNG download — export any chart as an image
• Auto-refresh — polls every 30 seconds while any run is in progress
• Browser notifications for new workflow failures (opt-in)
• CSV export from the Runs tab
• Multi-arch Docker image (amd64 + arm64)

Request Flow

Browser ──── request ────► Middleware (decrypt session cookie)
                                    │
                                    ├─ No token? ──► Redirect to /setup or /login
                                    │
                                    ▼ Valid session
                         /api/github/* routes
                                    │
                            Retrieve encrypted token
                            from session (server-side)
                                    │
                                    ▼
                          GitHub REST API
                         (Bearer token auth)
                                    │
                                    ▼
                           JSON response
                     (token never sent to browser)

Protection Layers

What Is Never Stored

• PAT in localStorage or sessionStorage — verified: 0 matches in src/
• PAT in API responses returned to the client — verified: 0 matches in src/app/api/
• PAT in server logs — only IP + timestamp logged on security events
• PAT as a URL query parameter — always POST body, HTTPS encrypted in transit
• OAuth token in the database — session-only, lives in the encrypted cookie

Self-Audit Commands

Run these in the project root to verify security claims yourself:

# PAT never in browser storage
grep -r "localStorage|sessionStorage" src/ --include="*.tsx" --include="*.ts"
# Expected: 0 matches ✓

# PAT never returned in API responses
grep -rn "return.*pat|json.*pat" src/app/api --include="*.ts"
# Expected: 0 matches ✓

# PAT never logged
grep -rn "console.*${.*pat|console.*pat)" src/ --include="*.ts" --include="*.tsx"
# Expected: 0 matches ✓

# XSS: dangerouslySetInnerHTML not used
grep -r "dangerouslySetInnerHTML" src/
# Expected: 0 matches ✓

# Check dependency vulnerabilities
npm audit --production
# Expected: 0 high/critical vulnerabilities ✓