.env.example

# GitLab MCP Server Environment Configuration
# Copy this file to .env and fill in your values

# ============================================================================
# REQUIRED CONFIGURATION
# ============================================================================

# GitLab Personal Access Token (REQUIRED when OAuth is disabled)
# Create at: GitLab → Settings → Access Tokens
# Required scopes: api, read_user, read_repository
# For full functionality add: write_repository, read_api, write_api
GITLAB_TOKEN=your_gitlab_token_here

# GitLab API Base URL (REQUIRED)
# Examples:
#   GitLab.com: https://gitlab.com
#   Self-hosted: https://gitlab.company.com
#   Custom port: https://gitlab.company.com:8443
GITLAB_API_URL=https://gitlab.com

# ============================================================================
# TRANSPORT CONFIGURATION
# ============================================================================

# Server host binding (default: 127.0.0.1)
# 127.0.0.1 = local only (SECURE — recommended for local development)
# 0.0.0.0   = all interfaces (REQUIRED inside Docker containers for port mapping)
#
# WARNING: 0.0.0.0 exposes the server to your entire network, including your GITLAB_TOKEN.
# Only use 0.0.0.0 when running inside Docker or when you explicitly need network access.
HOST=127.0.0.1

# Server port for HTTP/SSE modes
# Default: 3002
PORT=3002

# ============================================================================
# TLS/HTTPS CONFIGURATION (Direct TLS Termination)
# ============================================================================
# For reverse proxy TLS (nginx/envoy/caddy), see SSL.md

# Path to PEM certificate file
# SSL_CERT_PATH=/path/to/server.crt

# Path to PEM private key file
# SSL_KEY_PATH=/path/to/server.key

# Path to CA certificate chain (for client cert validation)
# SSL_CA_PATH=/path/to/ca.crt

# Passphrase for encrypted private keys
# SSL_PASSPHRASE=your_passphrase

# ============================================================================
# REVERSE PROXY CONFIGURATION
# ============================================================================
# When behind nginx, envoy, caddy, or traefik

# Trust proxy setting for X-Forwarded-* headers
# Values: true, false, loopback, linklocal, uniquelocal, or number of hops
# TRUST_PROXY=true

# ============================================================================
# OAUTH CONFIGURATION (Per-User Authentication)
# ============================================================================
# Enable OAuth mode for per-user GitLab authentication
# When enabled, each user authenticates with their own GitLab credentials

# Enable OAuth mode (disables GITLAB_TOKEN requirement)
OAUTH_ENABLED=false

# Secret for signing MCP JWT tokens (minimum 32 characters)
# Generate with: openssl rand -base64 32
# OAUTH_SESSION_SECRET=your_32_char_minimum_secret_here

# GitLab OAuth Application Client ID
# Create at: GitLab → Admin → Applications (or User → Settings → Applications)
# GITLAB_OAUTH_CLIENT_ID=your_client_id

# GitLab OAuth Application Client Secret (optional, for confidential apps)
# GITLAB_OAUTH_CLIENT_SECRET=your_client_secret

# OAuth scopes to request from GitLab (default: api,read_user)
# GITLAB_OAUTH_SCOPES=api,read_user

# MCP access token TTL in seconds (default: 3600 = 1 hour)
# OAUTH_TOKEN_TTL=3600

# MCP refresh token TTL in seconds (default: 604800 = 7 days)
# OAUTH_REFRESH_TOKEN_TTL=604800

# Device flow polling interval in seconds (default: 5)
# OAUTH_DEVICE_POLL_INTERVAL=5

# Device flow timeout in seconds (default: 300 = 5 minutes)
# OAUTH_DEVICE_TIMEOUT=300

# ============================================================================
# OPTIONAL GITLAB TARGETING
# ============================================================================

# Default project for operations that don't specify a target
# Format: "username/project" or "group/project" or project ID
GITLAB_PROJECT_ID=

# Comma-separated list of allowed project IDs (empty = all allowed)
# Use for restricting access to specific projects
GITLAB_ALLOWED_PROJECT_IDS=

# Default group for group-level operations
# Format: "group-name" or "parent-group/sub-group"
GITLAB_GROUP_PATH=

# ============================================================================
# FEATURE FLAGS
# ============================================================================

# Enable Work Items (Epics, Issues via GraphQL API)
USE_WORKITEMS=true

# Enable Labels functionality
USE_LABELS=true

# Enable Merge Requests functionality
USE_MRS=true

# Enable Files/Repository functionality
USE_FILES=true

# Enable Milestones functionality
USE_MILESTONE=true

# Enable CI/CD Pipelines functionality
USE_PIPELINE=true

# Enable CI/CD Variables functionality
USE_VARIABLES=true

# Enable Wiki functionality
USE_GITLAB_WIKI=true

# ============================================================================
# SECURITY AND ACCESS CONTROL
# ============================================================================

# Read-only mode (disables all write operations)
# Recommended for security-sensitive environments
GITLAB_READ_ONLY_MODE=false

# Regex pattern to deny specific tools
# Example: "delete.*|create.*" to block delete and create operations
GITLAB_DENIED_TOOLS_REGEX=

# ============================================================================
# TLS VERIFICATION
# ============================================================================

# Skip TLS certificate verification (INSECURE - use only for testing)
SKIP_TLS_VERIFY=false

# Path to custom CA certificate for GitLab server
# GITLAB_CA_CERT_PATH=/path/to/ca-bundle.crt

# Node.js TLS rejection (0 = disable verification, INSECURE)
# NODE_TLS_REJECT_UNAUTHORIZED=1

# ============================================================================
# NETWORK AND PROXY SETTINGS
# ============================================================================

# HTTP proxy for outbound requests
# HTTP_PROXY=http://proxy.company.com:8080

# HTTPS proxy for outbound requests
# HTTPS_PROXY=http://proxy.company.com:8080

# Comma-separated list of hosts to bypass proxy
NO_PROXY=localhost,127.0.0.1

# ============================================================================
# PERFORMANCE TUNING
# ============================================================================

# --- API Timeout Configuration ---
# Granular timeouts for different phases of HTTP requests to GitLab API.

# TCP connect timeout (default: 2000 = 2 seconds)
GITLAB_API_CONNECT_TIMEOUT_MS=2000
# Response headers timeout (default: 10000 = 10 seconds)
GITLAB_API_HEADERS_TIMEOUT_MS=10000
# Response body timeout (default: 30000 = 30 seconds)
GITLAB_API_BODY_TIMEOUT_MS=30000
# Tool handler timeout (default: 120000 = 2 minutes)
GITLAB_TOOL_TIMEOUT_MS=120000

# --- Connection Pool ---
# Maximum HTTP connections per GitLab instance (default: 25)
GITLAB_POOL_MAX_CONNECTIONS=25

# --- Retry Configuration ---
# Retry for idempotent operations (GET/HEAD/OPTIONS)
GITLAB_API_RETRY_ENABLED=true
GITLAB_API_RETRY_MAX_ATTEMPTS=3
GITLAB_API_RETRY_BASE_DELAY_MS=1000
GITLAB_API_RETRY_MAX_DELAY_MS=4000

# Node.js memory limit and options
NODE_OPTIONS=--max-old-space-size=512

# ============================================================================
# LOGGING AND DEBUGGING
# ============================================================================

# Log level: error, warn, info, debug, trace
LOG_LEVEL=info

# Log format using tokens: %time, %level, %name, %msg
# Default: "%msg" (minimal) - for daemonized environments where journald/systemd
# already provides timestamp, hostname, and process name
#
# Tokens:
#   %time  - Timestamp [HH:MM:SS.mmm]
#   %level - Log level (INFO, WARN, ERROR, DEBUG)
#   %name  - Logger name (gitlab-mcp)
#   %msg   - Log message with structured data
#
# Examples:
#   Minimal output: "StreamableHTTP endpoint endpoint=http://..."
#   Full output:    "[16:27:13.276] INFO (gitlab-mcp): StreamableHTTP endpoint..."
#
# LOG_FORMAT=%msg
# LOG_FORMAT=[%time] %level (%name): %msg
# LOG_FORMAT=%level: %msg

# JSON log output for log aggregators (Loki, ELK, Datadog)
# When true, outputs raw NDJSON (LOG_FORMAT is ignored)
# LOG_JSON=true

# Skip access logging for specific request patterns
# JSON array of filter rules. Request is skipped if ALL conditions in a rule match.
# Properties (all optional):
#   - method: HTTP method (exact, case-insensitive)
#   - path: Request path (exact, or prefix if ends with *)
#   - userAgent: Substring match in User-Agent (case-insensitive)
#
# Default: [{"method":"GET","path":"/","userAgent":"claude-code"}] (skip Claude Code polling)
# Set to '[]' to log all requests.
#
# Examples:
#   Skip Claude Code polling (default): [{"method":"GET","path":"/","userAgent":"claude-code"}]
#   Skip all HEAD requests: [{"method":"HEAD","path":"/*"}]
#   Skip monitoring tools: [{"userAgent":"prometheus"},{"userAgent":"datadog"}]
#   Log all requests: []
#
# Note: /health endpoint is registered before access logging and never logged.
#
# LOG_FILTER='[{"method":"GET","path":"/","userAgent":"claude-code"}]'

# Node.js environment
NODE_ENV=development

# ============================================================================
# ADVANCED/EXPERIMENTAL
# ============================================================================

# Cookie-based authentication (alternative to token)
# Path to Netscape cookie file for GitLab authentication
# GITLAB_AUTH_COOKIE_PATH=/path/to/cookies.txt

# Legacy GitLab instance mode (for older GitLab versions)
# GITLAB_IS_OLD=false

# ============================================================================
# USAGE NOTES
# ============================================================================

# Transport Mode:
# - Set PORT to enable HTTP server with dual transport (SSE + StreamableHTTP)
# - Unset PORT for stdio mode (direct MCP communication)

# Authentication Modes:
# 1. Static Token (default): Set GITLAB_TOKEN
# 2. OAuth Mode: Set OAUTH_ENABLED=true and configure OAuth settings
#    - Each user authenticates with their own GitLab credentials
#    - Supports GitLab Device Flow for MCP clients

# TLS/HTTPS Options:
# 1. Direct TLS: Set SSL_CERT_PATH and SSL_KEY_PATH
# 2. Reverse Proxy: Use nginx/envoy/caddy for TLS termination
#    See SSL.md for detailed configuration examples

# Security Best Practices:
# - Use read-only mode for security-sensitive environments
# - Limit tool access with GITLAB_DENIED_TOOLS_REGEX
# - Use environment-specific API URLs and tokens
# - Enable TLS for production deployments