Environment Setup

Configure your environment variables and settings

Environment Variables Reference

This document provides detailed information about all environment variables used in the GitLab Claude Manager application.

Quick Start

  1. Copy the example file:

    cp env.example .env

  2. Configure required variables:

    • NEXTAUTH_SECRET - Generate with openssl rand -base64 32
    • NEXTAUTH_URL - Your application URL

  3. Start the application:

    pnpm dev

Production Deployment

For production deployments, use the following template. Generate secure values for each secret before deploying.

Minimum Production Configuration

Required - generate with: openssl rand -base64 32

NEXTAUTH_SECRET=<your-generated-secret>

Required - your production URL (no trailing slash)

NEXTAUTH_URL=https://your-domain.com

Required for production - generate with: openssl rand -hex 32

Prevents unauthorized first-user account creation

INITIAL_SIGNUP_TOKEN=<your-generated-token>

Recommended Production Configuration

# ---- Required ----
NEXTAUTH_SECRET=<your-generated-secret>
NEXTAUTH_URL=https://your-domain.com
INITIAL_SIGNUP_TOKEN=<your-generated-token>

# ---- Security (recommended) ----
ALLOWED_IPS=<your-trusted-ips>
API_RATE_LIMIT=100

# ---- Integration credentials (or configure via Dashboard UI) ----
ANTHROPIC_API_KEY=<your-anthropic-key>
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=<your-gitlab-token>
ALLOWED_GITLAB_HOSTS=gitlab.com

Generate Secure Values

Run these commands to generate the required secrets:

Generate NEXTAUTH_SECRET

echo "NEXTAUTH_SECRET=$(openssl rand -base64 32)"

Generate INITIAL_SIGNUP_TOKEN

echo "INITIAL_SIGNUP_TOKEN=$(openssl rand -hex 32)"

Environment Variables

Required Variables

NEXTAUTH_SECRET

  • Required: Yes
  • Description: Secret key for NextAuth.js JWT token signing and encryption
  • Format: String (minimum 32 characters recommended)
  • Generate: openssl rand -base64 32
  • Example: jFQOQfMxoJmilm9tKJUzzL1lMnihAaAl4jcoTgBkH9k=

NEXTAUTH_URL

  • Required: Yes
  • Description: The canonical URL of your application
  • Format: Full URL with protocol
  • Development: http://localhost:3000
  • Production: https://your-domain.com

API Key Configuration

Recommended: Use the Dashboard to generate and manage API keys instead of environment variables. Navigate to Dashboard → Account Security to generate keys. Dashboard-generated keys are stored in workspaces/api-keys.json and are automatically validated.

VALID_API_KEYS

  • Required: No (use Dashboard instead)
  • Description: Comma-separated list of valid API keys for external clients (legacy/fallback)
  • Format: key1,key2,key3
  • Generate: openssl rand -hex 32 (for each key)
  • Example: abc123def456,xyz789ghi012
  • Note: Only needed if not using dashboard-generated keys

ADMIN_API_KEY

  • Required: No (use Dashboard instead)
  • Description: Admin API key with elevated privileges (legacy/fallback)
  • Format: String (32+ characters recommended)
  • Generate: openssl rand -hex 32
  • Note: Only needed if not using dashboard-generated keys

Rate Limiting & Security

API_RATE_LIMIT

  • Required: No
  • Description: Maximum API requests per hour per client
  • Format: Integer
  • Default: 100
  • Example: 200

ALLOWED_IPS

  • Required: No

  • Description: IP whitelist for API access.

  • Format: Comma-separated IPs or * for all

  • Default: Allow all (if not set)

  • Examples:

    • 192.168.1.100,10.0.0.50 - Specific IPs
    • * - Allow all
    • Empty - Allow all

  • Reverse proxy note (Traefik/Caddy):

    • The app determines the client IP from x-forwarded-for (first value) or x-real-ip.

    • Only enable ALLOWED_IPS if your reverse proxy is trusted and overwrites/sanitizes these headers.

    • Do not expose the app container/port directly to the internet; only your reverse proxy should be able to reach it (private Docker network / firewall).

    • Caddy example (overwrite headers):

      reverse_proxy workflow-app:3000 {
  header_up X-Forwarded-For {remote_host}
  header_up X-Real-IP {remote_host}
}

    • Traefik: configure forwarded headers so untrusted client-supplied X-Forwarded-* values are not accepted (use trusted proxy hops / trustedIPs and keep insecure=false).

Claude Code Integration

ANTHROPIC_API_KEY

  • Required: No (can be set via UI)
  • Description: API key for Claude Code integration
  • Format: String
  • Get Key: https://console.anthropic.com/
  • Note: Can also be configured through the web UI

CLAUDE_CODE_AUTH_MODE

  • Required: No
  • Description: Controls how the app authenticates the claude CLI subprocess
  • Values:
    • auto (default): use an API key if available, otherwise rely on CLI login
    • cli: never pass ANTHROPIC_API_KEY to the claude subprocess (useful for Claude subscription accounts that require interactive login)
  • Example: CLAUDE_CODE_AUTH_MODE=cli

GitLab Integration

GITLAB_TOKEN

  • Required: No (can be set via UI)
  • Description: GitLab personal access token
  • Format: String (starts with glpat-)
  • Scopes Required: api, read_repository, write_repository
  • Create: https://gitlab.com/-/profile/personal_access_tokens
  • Note: Can also be configured through the web UI

GITLAB_URL

  • Required: No
  • Description: GitLab instance URL
  • Default: https://gitlab.com
  • Example: https://gitlab.company.com (for self-hosted)

ALLOWED_GITLAB_HOSTS

  • Required: No
  • Description: Allowed GitLab hosts for security
  • Format: Comma-separated hostnames
  • Default: gitlab.com
  • Example: gitlab.com,gitlab.company.com

Application Configuration

NODE_ENV

  • Required: No (automatically set)
  • Description: Node environment
  • Values: development | production | test
  • Note: Set automatically by Next.js and npm scripts

NEXT_TELEMETRY_DISABLED

  • Required: No
  • Description: Disable Next.js telemetry
  • Values: 1 (disabled) or 0 (enabled)
  • Default: 0
  • Note: Automatically set to 1 in CI/CD

LOG_LEVEL

  • Required: No
  • Description: Application logging level
  • Values: debug | info | warn | error
  • Default: info

First User Signup Hardening (Recommended for Production)

INITIAL_SIGNUP_TOKEN

  • Required: No
  • Description: If set, creating the first (initial) dashboard user requires providing this token during signup.
  • Format: String (32+ characters recommended)
  • Example: openssl rand -hex 32
  • Notes:
    • Leave unset for local/dev convenience.
    • Set this in production to prevent “first user wins” account takeover if the app is accidentally exposed before setup.

Workspace Configuration (Advanced)

MAX_WORKSPACE_SIZE_MB

  • Required: No
  • Description: Maximum workspace size in megabytes
  • Format: Integer
  • Default: 500

MAX_CONCURRENT_WORKSPACES

  • Required: No
  • Description: Maximum concurrent workspaces
  • Format: Integer
  • Default: 3

TEMP_DIR_PREFIX

  • Required: No
  • Description: Prefix for temporary workspace directories
  • Format: String
  • Default: gitlab-claude-

Configuration Methods

The GitLab Claude Manager supports multiple configuration methods:

1. Environment Variables (Recommended for Development)

In your .env file:

NEXTAUTH_SECRET=your-secret
GITLAB_TOKEN=your-token

2. UI Configuration (Recommended for Production)

  • Navigate to Dashboard → Settings
  • Enter your credentials in the web interface
  • Settings are stored securely in the workspace

3. CI/CD Variables (For GitLab CI/CD)

  • Set variables in GitLab: Settings → CI/CD → Variables
  • Variables are automatically available in pipelines
  • Mark sensitive variables as "Masked" and "Protected"

Security Best Practices

  1. Never commit .env files

    • The .env file is in .gitignore
    • Use env.example as a template

  2. Use strong secrets

    • Minimum 32 characters for all secrets
    • Use cryptographically random generation

  3. Rotate credentials regularly

    • Change API keys every 90 days
    • Immediately rotate if compromised

  4. Separate environments

    • Use different secrets for dev/staging/prod
    • Never use production secrets in development

  5. Limit API access

    • Enable IP whitelisting in production
    • Set appropriate rate limits
    • Use minimal API key permissions

  6. Secure storage

    • Use environment variables or secure vaults
    • Don't hardcode secrets in code
    • Use CI/CD secret management

Generating Secure Keys

Using OpenSSL (Recommended)

For NEXTAUTH_SECRET:

openssl rand -base64 32

For API keys:

openssl rand -hex 32

Using Node.js

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Using Python

python3 -c "import secrets; print(secrets.token_hex(32))"

Troubleshooting

Missing NEXTAUTH_SECRET

Error: NEXTAUTH_SECRET is required but not set

Solution:

Generate a secret:

openssl rand -base64 32

Add to .env:

echo "NEXTAUTH_SECRET=<generated-secret>" >> .env

API Authentication Fails

Error: Invalid API key or Authentication service not configured

Solutions:

  1. Generate an API key in the Dashboard (Dashboard → Account Security)
  2. Or set VALID_API_KEYS or ADMIN_API_KEY in environment variables
  3. Verify API key format (no spaces, correct delimiter)
  4. Check that the key matches exactly (case-sensitive)
  5. Ensure workspaces/api-keys.json exists if using dashboard-generated keys

IP Blocked

Error: Access denied from this IP address

Solutions:

  1. Add your IP to ALLOWED_IPS
  2. Use ALLOWED_IPS=* to allow all (development only)
  3. Check x-forwarded-for header if behind proxy

Configuration Priority

The application checks for configuration in this order:

API Keys (for API authentication)

  1. Dashboard-generated keys (stored in workspaces/api-keys.json)
  2. Admin API key (ADMIN_API_KEY environment variable)
  3. Client API keys (VALID_API_KEYS environment variable)

Other Settings

  1. Runtime configuration (set via Dashboard UI, stored in workspaces/app-config.json)
  2. Environment variables (.env file or system)
  3. Default values (hardcoded fallbacks)

Related Documentation