Configuration link

gitlab-summary requires a GitLab access token to authenticate with your GitLab instance. This guide covers token creation, secure storage, and configuration options.

GitLab Access Token link

Creating a Personal Access Token link

1. Log in to GitLab and navigate to your user settings
2. Select “Access Tokens” from the left sidebar
3. Create a new token with:
   • Name: gitlab-summary (or any descriptive name)
   • Scopes: Check read_api
   • Expiration: Set based on your security policy
4. Click “Create personal access token”
5. Copy the token immediately (you won’t see it again)

Creating a Group Access Token link

For group-level access (recommended for teams):

1. Navigate to your GitLab group
2. Go to Settings → Access Tokens
3. Create a new token with:
   • Name: gitlab-summary
   • Role: Reporter or higher
   • Scopes: Check read_api
4. Copy the generated token

Storing Your Token link

gitlab-summary stores tokens securely using platform-specific APIs.

Set Token (Interactive) link

  gitlab-summary token set --url https://gitlab.example.com
  

You’ll be prompted to enter your token (input is masked):

  Enter your GitLab token: ********
Token stored successfully.
  

📸 Screenshot placeholder: cli-token-setup.png Description: Terminal showing gitlab-summary token set command with URL parameter and masked password input prompt

Set Token (Non-Interactive) link

For scripts or automation:

  echo "your-token-here" | gitlab-summary token set --url https://gitlab.example.com
  

⚠️ Warning: Never commit tokens to version control or hardcode them in scripts.

Token Storage Locations link

gitlab-summary uses platform-specific secure storage:

macOS link

Keychain — Tokens stored in macOS Keychain Access

• Service: gitlab-summary
• Account: gitlab-token
• View in: Applications → Utilities → Keychain Access

Windows link

DPAPI (Data Protection API) — Encrypted storage using Windows credentials

• Location: %USERPROFILE%\.gitlab-summary\protected-token.dat
• Encrypted per-user, cannot be read by other accounts

Linux link

.NET DataProtection with file-based key storage

• Location: ~/.gitlab-summary/protected-token.dat
• Keys: ~/.microsoft/usersecrets/
• Permissions: Read/write for current user only (0600)

Token Management link

View Stored Token (Masked) link

  gitlab-summary token show
  

Output:

  GitLab URL: https://gitlab.example.com
Token: glpat-xxxx...xxxx (masked)
  

Clear Token link

  gitlab-summary token clear
  

Removes the stored token from secure storage.

GitLab URL Configuration link

Set URL link

  gitlab-summary url set --url https://gitlab.example.com
  

View URL link

  gitlab-summary url show
  

Override URL Per Command link

You can override the configured URL for individual commands:

  gitlab-summary pipelines --group my-org --url https://different-gitlab.com
  

Configuration File link

Settings are stored in ~/.gitlab-summary/settings.json:

  {
  "GitLabUrl": "https://gitlab.example.com"
}
  

Location by Platform:

• macOS/Linux: ~/.gitlab-summary/settings.json
• Windows: %USERPROFILE%\.gitlab-summary\settings.json

AI Analysis Configuration (Optional) link

To enable AI-powered failure analysis, you need GitHub Copilot access.

Prerequisites link

• GitHub Copilot subscription (Individual, Business, or Enterprise)
• GitHub CLI (gh) installed and authenticated

Verify Copilot Access link

  gh copilot --version
  

If installed:

  gh version 2.x.x (2024-xx-xx)
  

Install GitHub CLI link

macOS:

  brew install gh
  

Windows:

  winget install --id GitHub.cli
  

Linux:

  # Debian/Ubuntu
sudo apt install gh

# Fedora/RHEL
sudo dnf install gh

# Arch
sudo pacman -S github-cli
  

Authenticate link

  gh auth login
  

Follow the prompts to authenticate with GitHub.

AI Model Selection (Optional) link

Choose which GitHub Copilot model to use for AI analysis.

Available Models link

• claude-sonnet-4-5 (default) — Fast, efficient, and accurate
• claude-opus-4 — Most capable, slower, best for complex analysis
• gpt-4 — OpenAI model alternative

Via CLI Parameter link

  gitlab-summary serve --group my-org --ai-model claude-opus-4
  

Via Environment Variable link

  export COPILOT_MODEL=claude-opus-4
gitlab-summary serve --group my-org
  

Via Docker link

Set in .env file:

  COPILOT_MODEL=claude-opus-4
  

Or pass directly:

  docker run -e COPILOT_MODEL=claude-opus-4 ...
  

Note: The environment variable takes precedence over the CLI parameter.

Custom System Prompt link

You can customize the AI analysis prompt via the dashboard settings.

Via Dashboard link

1. Start the dashboard: gitlab-summary serve --group my-org --open
2. Click the settings icon in the top bar
3. Edit the System Prompt text area
4. Click Save

Prompt Storage link

Custom prompts are stored in: ~/.gitlab-summary/ai-system-prompt.txt

Default Prompt link

The default system prompt focuses on:

• Root cause identification
• Actionable fixes
• Clear, concise explanations
• Context from logs and job metadata

Environment Variables link

gitlab-summary supports these environment variables:

Example:

  export GITLAB_URL=https://gitlab.company.com
export COPILOT_MODEL=claude-opus-4
gitlab-summary pipelines --group my-org
  

Security Best Practices link

Token Security link

✅ DO:

• Use tokens with minimal required scopes (read_api only)
• Set expiration dates on tokens
• Rotate tokens regularly
• Use group tokens instead of personal tokens when possible
• Store tokens using the built-in secure storage

❌ DON’T:

• Commit tokens to version control
• Share tokens between users
• Use tokens with write permissions
• Store tokens in plain text files
• Include tokens in screenshots or logs

File Permissions link

Ensure configuration directory has proper permissions:

  # Linux/macOS
chmod 700 ~/.gitlab-summary
chmod 600 ~/.gitlab-summary/settings.json
chmod 600 ~/.gitlab-summary/protected-token.dat
  

Troubleshooting link

“Unable to authenticate with GitLab” link

Causes:

• Token is expired or invalid
• Token lacks read_api scope
• Wrong GitLab URL configured
• Network connectivity issues

Solution:

  # Verify URL
gitlab-summary url show

# Re-set token
gitlab-summary token set --url https://gitlab.example.com

# Test with a simple command
gitlab-summary pipelines --group your-group --since 1h
  

“Token not found” link

Solution:

  gitlab-summary token set --url https://gitlab.example.com
  

AI analysis not working link

Causes:

• GitHub CLI not installed
• Not authenticated with GitHub
• No Copilot subscription

Solution:

  # Check GitHub CLI
gh --version

# Authenticate
gh auth login

# Verify Copilot access
gh copilot --version
  

Next Steps link

• Quick Start Guide — Try your first commands
• CLI Reference — Complete command documentation
• Dashboard Guide — Launch the web interface

See Also link

• Installation — Install gitlab-summary
• CLI Reference — All CLI commands
• Security — Advanced security topics