@dev-boy/gitlab-proxy

HTTP proxy server for GitLab Self-Hosted instances behind a firewall. Deploy in your network and expose via ngrok to connect with Dev Boy.

Problem

Your GitLab Self-Hosted instance is in a private network, not accessible from the internet. Dev Boy cloud service cannot reach it directly.

Solution

┌──────────────────────────────────────────────────────────────────┐
│                        Your Private Network                       │
│                                                                    │
│  ┌───────────────┐     ┌──────────────┐     ┌───────────────────┐ │
│  │   Dev Boy     │ --> │ gitlab-proxy │ --> │  GitLab Self-     │ │
│  │   Cloud       │     │  (you run)   │     │  Hosted           │ │
│  └───────────────┘     └──────────────┘     └───────────────────┘ │
│         │                     │                                    │
│         └─────────────────────┘                                    │
│              via ngrok tunnel                                      │
└──────────────────────────────────────────────────────────────────┘

Quick Start

1. Install and Run the Proxy

# Using npx (recommended)
GITLAB_URL=https://gitlab.yourcompany.local PROXY_TOKEN=your-secret-token npx @dev-boy/gitlab-proxy

# Or install globally
npm install -g @dev-boy/gitlab-proxy
GITLAB_URL=https://gitlab.yourcompany.local PROXY_TOKEN=your-secret-token gitlab-proxy

2. Expose via ngrok

ngrok http 3001

Copy the HTTPS URL from ngrok (e.g., https://abc123.ngrok.io)

3. Configure Dev Boy

In Dev Boy Dashboard, when adding GitLab Self-Hosted integration:

1. Fill in GitLab Server URL, Client ID, Client Secret as usual
2. Expand Proxy settings (optional)
3. Enter:
   • Proxy URL: Your ngrok URL (e.g., https://abc123.ngrok.io)
   • Proxy Token: Your PROXY_TOKEN value

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GITLAB_URL | Yes | - | Target GitLab URL (e.g., https://gitlab.company.local) | | PROXY_TOKEN | Yes | - | Secret token for authenticating requests to this proxy | | PORT | No | 3001 | Port to listen on | | VERBOSE | No | false | Enable verbose logging | | INSECURE | No | false | Skip TLS certificate verification ⚠️ |

Examples

# Basic usage
GITLAB_URL=https://gitlab.company.local PROXY_TOKEN=secret123 gitlab-proxy

# Custom port with verbose logging
GITLAB_URL=https://gitlab.local PROXY_TOKEN=mytoken PORT=8080 VERBOSE=true gitlab-proxy

# Self-signed certificate (skip TLS verification) ⚠️
GITLAB_URL=https://gitlab.local PROXY_TOKEN=secret INSECURE=true gitlab-proxy

How It Works

1. Proxy server runs in your network where GitLab is accessible
2. Ngrok tunnel exposes the proxy to the internet
3. Dev Boy sends requests to ngrok URL with X-Proxy-Token header
4. Proxy validates the token and forwards requests to GitLab
5. GitLab responses are returned through the same path

Authentication Flow

Dev Boy Request:
  Headers:
    X-Proxy-Token: <your-proxy-token>    # For proxy authentication
    X-GitLab-Token: <gitlab-oauth-token> # GitLab access token

Proxy Processing:
  1. Validate X-Proxy-Token
  2. Remove X-Proxy-Token header
  3. Convert X-GitLab-Token to Authorization: Bearer <token>
  4. Forward to GitLab

API Endpoints

Health Check

curl http://localhost:3001/health

No authentication required. Returns:

{
  "status": "ok",
  "target": "https://gitlab.yourcompany.local",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

All Other Routes

All requests are proxied to GitLab. Requires authentication via one of:

• Header: X-Proxy-Token: <your-token>
• Header: Authorization: Bearer <your-token>

Security

• Token-based auth: Only requests with valid PROXY_TOKEN are forwarded
• Header sanitization: Proxy headers are removed before forwarding to GitLab
• SSL verification: Proxy verifies SSL certificates of target GitLab (unless INSECURE=true)

⚠️ Warning about INSECURE mode

Setting INSECURE=true disables TLS certificate verification. This is a security risk because:

• Man-in-the-middle attacks become possible
• Certificate errors are silently ignored
• You cannot verify you're connecting to the real GitLab server

Only use INSECURE=true for:

• Development/testing environments
• GitLab instances with self-signed certificates
• Temporary debugging of TLS issues

Never use in production if you have a valid SSL certificate!

Recommendations

1. Use a strong, random PROXY_TOKEN
2. Keep ngrok URL private (it's effectively your proxy password)
3. Run proxy on a dedicated machine or container
4. Monitor proxy logs for suspicious activity
5. Avoid INSECURE=true in production - get a proper SSL certificate instead

Troubleshooting

"401 Unauthorized"

Missing X-Proxy-Token header. Ensure Dev Boy has proxy configuration.

"403 Forbidden"

Invalid PROXY_TOKEN. Check that token matches in proxy and Dev Boy.

"502 Bad Gateway"

Proxy cannot reach GitLab. Check:

• GITLAB_URL is correct
• GitLab is accessible from proxy machine
• Network/firewall allows connection

SSL/TLS Certificate Errors

If you see errors like UNABLE_TO_VERIFY_LEAF_SIGNATURE or CERT_HAS_EXPIRED:

1. Best solution: Fix the certificate on GitLab server
2. Temporary workaround: Use INSECURE=true (⚠️ security risk!)

GITLAB_URL=https://gitlab.local PROXY_TOKEN=secret INSECURE=true gitlab-proxy

Connection refused

Proxy not running or wrong port. Check:

• Proxy process is running
• ngrok is connected to correct port

Development

# Clone the repository
git clone https://github.com/your-org/dev-boy-monorepo.git
cd packages/gitlab-proxy

# Install dependencies
pnpm install

# Run in development
GITLAB_URL=https://gitlab.local PROXY_TOKEN=test pnpm run dev

# Build
pnpm run build

License

MIT