@dev-boy/proxy

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

Problem

Your GitLab or Jira 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     │ --> │ devboy-proxy │ --> │  GitLab Self-Hosted    │  │
│  │   Cloud       │     │  (you run)   │     │         OR             │  │
│  └───────────────┘     └──────────────┘     │  Jira Self-Hosted      │  │
│         │                     │              └────────────────────────┘  │
│         └─────────────────────┘                                          │
│              via ngrok tunnel                                            │
└──────────────────────────────────────────────────────────────────────────┘

Quick Start

1. Install and Run the Proxy

For GitLab:

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

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

# Backwards compatibility - GITLAB_URL still works
GITLAB_URL=https://gitlab.yourcompany.local PROXY_TOKEN=your-secret-token devboy-proxy

For Jira:

# Using npx
TARGET_URL=https://jira.yourcompany.local TARGET_TYPE=jira PROXY_TOKEN=your-secret-token npx @dev-boy/proxy

# Or install globally
TARGET_URL=https://jira.yourcompany.local TARGET_TYPE=jira PROXY_TOKEN=your-secret-token devboy-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 | No* | - | GitLab server URL (e.g., https://gitlab.company.local) | | JIRA_URL | No* | - | Jira server URL (e.g., https://jira.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 ⚠️ |

*At least one of GITLAB_URL or JIRA_URL is required. You can configure both for single proxy instance.

Examples

Single provider (GitLab only):

GITLAB_URL=https://gitlab.company.local PROXY_TOKEN=secret123 devboy-proxy

Single provider (Jira only):

JIRA_URL=https://jira.company.local PROXY_TOKEN=secret123 devboy-proxy

Both providers (recommended):

GITLAB_URL=https://gitlab.company.local \
JIRA_URL=https://jira.company.local \
PROXY_TOKEN=secret123 \
devboy-proxy

With custom port and verbose logging:

GITLAB_URL=https://gitlab.local \
JIRA_URL=https://jira.local \
PROXY_TOKEN=mytoken \
PORT=8080 \
VERBOSE=true \
devboy-proxy

Self-signed certificate (skip TLS verification) ⚠️:

GITLAB_URL=https://gitlab.local \
JIRA_URL=https://jira.local \
PROXY_TOKEN=secret \
INSECURE=true \
devboy-proxy

Multi-Provider Configuration

Can I proxy both GitLab AND Jira at the same time?

Yes! You can run a single proxy instance handling both GitLab and Jira simultaneously.

Single Proxy Instance (Recommended)

Run one proxy with both GITLAB_URL and JIRA_URL:

# Using npx
GITLAB_URL=https://gitlab.company.local \
JIRA_URL=https://jira.company.local \
PROXY_TOKEN=your-secret-token \
npx @dev-boy/proxy

# Or install globally
npm install -g @dev-boy/proxy
GITLAB_URL=https://gitlab.company.local \
JIRA_URL=https://jira.company.local \
PROXY_TOKEN=your-secret-token \
devboy-proxy

Then expose via ngrok:

ngrok http 3001

That's it! One proxy, one ngrok tunnel, simpler deployment.

How Header-Based Routing Works

The proxy determines the target by inspecting authorization headers:

• X-GitLab-Token present → Routes to GitLab server
• X-Jira-Token present → Routes to Jira server
• Both present → 400 Bad Request (ambiguous)
• Neither present → 400 Bad Request (no target)

Dev Boy backend automatically adds the correct header based on integration type.

Request Flow Example

GitLab request:

POST https://abc123.ngrok.io/api/v4/projects
Headers:
  X-Proxy-Token: your-secret-token
  X-GitLab-Token: <gitlab-oauth-token>

→ Proxy sees X-GitLab-Token
→ Routes to https://gitlab.company.local/api/v4/projects
→ Transforms X-GitLab-Token to Authorization: Bearer <token>

Jira request:

GET https://abc123.ngrok.io/rest/api/2/project
Headers:
  X-Proxy-Token: your-secret-token
  X-Jira-Token: <username:password>

→ Proxy sees X-Jira-Token
→ Routes to https://jira.company.local/rest/api/2/project
→ Transforms X-Jira-Token to Authorization: Basic <base64>

Why Header-Based Routing?

Compared to path-based routing (/gitlab/*, /jira/*):

• ✅ Simpler deployment - one process, one ngrok tunnel
• ✅ Cleaner URLs - no path prefixes needed
• ✅ Automatic routing - backend sends plain endpoints
• ✅ Better scalability - add more providers without URL changes
• ✅ Clearer intent - header explicitly declares target

How It Works

1. Proxy server runs in your network where GitLab/Jira 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 target server (GitLab or Jira)
5. Server responses are returned through the same path

Authentication Flow

For GitLab:

Dev Boy Request to /gitlab/api/v4/projects:
  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 at /api/v4/projects

For Jira:

Dev Boy Request to /jira/rest/api/2/project:
  Headers:
    X-Proxy-Token: <your-proxy-token>       # For proxy authentication
    X-Jira-Token: <username:password or token> # Jira credentials

Proxy Processing:
  1. Validate X-Proxy-Token
  2. Remove X-Proxy-Token header
  3. Convert X-Jira-Token to Authorization: Basic <base64> or Bearer <token>
  4. Forward to Jira at /rest/api/2/project

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 the target server (GitLab or Jira). Requires authentication via one of:

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

GitLab routes: All requests to /gitlab/* are forwarded to GitLab server

Jira routes: All requests to /jira/* are forwarded to Jira server

Security

• Token-based auth: Only requests with valid PROXY_TOKEN are forwarded
• Header sanitization: Proxy headers are removed before forwarding to target server
• SSL verification: Proxy verifies SSL certificates of target server (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/Jira 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 target server. Check:

• TARGET_URL (or GITLAB_URL) is correct
• Target server (GitLab/Jira) 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 target server
2. Temporary workaround: Use INSECURE=true (⚠️ security risk!)

# GitLab
TARGET_URL=https://gitlab.local TARGET_TYPE=gitlab PROXY_TOKEN=secret INSECURE=true devboy-proxy

# Jira
TARGET_URL=https://jira.local TARGET_TYPE=jira PROXY_TOKEN=secret INSECURE=true devboy-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/proxy

# Install dependencies
pnpm install

# Run in development - GitLab
TARGET_URL=https://gitlab.local TARGET_TYPE=gitlab PROXY_TOKEN=test pnpm run dev

# Run in development - Jira
TARGET_URL=https://jira.local TARGET_TYPE=jira PROXY_TOKEN=test pnpm run dev

# Build
pnpm run build

License

MIT