# 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
# Use 0.0.0.0 for external access, 127.0.0.1 for local only
HOST=0.0.0.0
# 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
