Navigate to

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

Copy the example file:
```
cp env.example .env
```
Configure required variables:
- NEXTAUTH_SECRET - Generate with openssl rand -base64 32
- NEXTAUTH_URL - Your application URL
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 (for GitLab repositories)
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=<your-gitlab-token>
ALLOWED_GITLAB_HOSTS=gitlab.com

# GitHub (for GitHub repositories)
GITHUB_TOKEN=<your-github-token>

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

GitHub Integration

GITHUB_TOKEN

Required: No (can be set via UI)
Description: GitHub personal access token for pull request creation
Format: String (starts with ghp_ for fine-grained tokens or github_pat_ for classic tokens)
Scopes Required: repo (full repository access)
Create: https://github.com/settings/tokens
Note: Can also be configured through the Dashboard UI

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

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

Never commit .env files
- The .env file is in .gitignore
- Use env.example as a template
Use strong secrets
- Minimum 32 characters for all secrets
- Use cryptographically random generation
Rotate credentials regularly
- Change API keys every 90 days
- Immediately rotate if compromised
Separate environments
- Use different secrets for dev/staging/prod
- Never use production secrets in development
Limit API access
- Enable IP whitelisting in production
- Set appropriate rate limits
- Use minimal API key permissions
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:

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

IP Blocked

Error: Access denied from this IP address

Solutions:

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

Configuration Priority

The application checks for configuration in this order:

API Keys (for API authentication)

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

Other Settings

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

API Authentication - Detailed auth setup
Docker Configuration - Docker environment variables
Quick Start Guide - Getting started
Credentials Management - Managing tokens and keys

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

Copy the example file:
```
cp env.example .env
```
Configure required variables:
- NEXTAUTH_SECRET - Generate with openssl rand -base64 32
- NEXTAUTH_URL - Your application URL
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 (for GitLab repositories)
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=<your-gitlab-token>
ALLOWED_GITLAB_HOSTS=gitlab.com

# GitHub (for GitHub repositories)
GITHUB_TOKEN=<your-github-token>

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

GitHub Integration

GITHUB_TOKEN

Required: No (can be set via UI)
Description: GitHub personal access token for pull request creation
Format: String (starts with ghp_ for fine-grained tokens or github_pat_ for classic tokens)
Scopes Required: repo (full repository access)
Create: https://github.com/settings/tokens
Note: Can also be configured through the Dashboard UI

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

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

Never commit .env files
- The .env file is in .gitignore
- Use env.example as a template
Use strong secrets
- Minimum 32 characters for all secrets
- Use cryptographically random generation
Rotate credentials regularly
- Change API keys every 90 days
- Immediately rotate if compromised
Separate environments
- Use different secrets for dev/staging/prod
- Never use production secrets in development
Limit API access
- Enable IP whitelisting in production
- Set appropriate rate limits
- Use minimal API key permissions
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:

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

IP Blocked

Error: Access denied from this IP address

Solutions:

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

Configuration Priority

The application checks for configuration in this order:

API Keys (for API authentication)

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

Other Settings

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

API Authentication - Detailed auth setup
Docker Configuration - Docker environment variables
Quick Start Guide - Getting started
Credentials Management - Managing tokens and keys

Environment Variables Reference

Quick Start

Production Deployment

Minimum Production Configuration

Recommended Production Configuration

Generate Secure Values

Environment Variables

Required Variables

NEXTAUTH_SECRET

NEXTAUTH_URL

API Key Configuration

VALID_API_KEYS

ADMIN_API_KEY

Rate Limiting & Security

API_RATE_LIMIT

ALLOWED_IPS

Claude Code Integration

ANTHROPIC_API_KEY

CLAUDE_CODE_AUTH_MODE

GitLab Integration

GITLAB_TOKEN

GITLAB_URL

ALLOWED_GITLAB_HOSTS

GitHub Integration

GITHUB_TOKEN

Application Configuration

NODE_ENV

NEXT_TELEMETRY_DISABLED

LOG_LEVEL

First User Signup Hardening (Recommended for Production)

INITIAL_SIGNUP_TOKEN

Workspace Configuration (Advanced)

MAX_WORKSPACE_SIZE_MB

MAX_CONCURRENT_WORKSPACES

TEMP_DIR_PREFIX

Configuration Methods

1. Environment Variables (Recommended for Development)

2. UI Configuration (Recommended for Production)

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

Security Best Practices

Generating Secure Keys

Using OpenSSL (Recommended)

Using Node.js

Using Python

Troubleshooting

Missing NEXTAUTH_SECRET

API Authentication Fails

IP Blocked

Configuration Priority

API Keys (for API authentication)

Other Settings

Related Documentation

Environment Variables Reference

Quick Start

Production Deployment

Minimum Production Configuration

Recommended Production Configuration

Generate Secure Values

Environment Variables

Required Variables

NEXTAUTH_SECRET

NEXTAUTH_URL

API Key Configuration

VALID_API_KEYS

ADMIN_API_KEY

Rate Limiting & Security

API_RATE_LIMIT

ALLOWED_IPS

Claude Code Integration

ANTHROPIC_API_KEY

CLAUDE_CODE_AUTH_MODE

GitLab Integration

GITLAB_TOKEN

GITLAB_URL

ALLOWED_GITLAB_HOSTS

GitHub Integration

GITHUB_TOKEN

Application Configuration

NODE_ENV

NEXT_TELEMETRY_DISABLED