Configuration

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

Creating a Personal Access Token

  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

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

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

Set Token (Interactive) 

  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)

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

gitlab-summary uses platform-specific secure storage:

macOS

Keychain — Tokens stored in macOS Keychain Access

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

Windows

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

.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

View Stored Token (Masked) 

  gitlab-summary token show

Output:

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

Clear Token 

  gitlab-summary token clear

Removes the stored token from secure storage.

GitLab URL Configuration

Set URL 

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

View URL 

  gitlab-summary url show

Override URL Per Command

You can override the configured URL for individual commands:

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

Configuration File

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)

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

Prerequisites

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

Verify Copilot Access 

  gh copilot --version

If installed:

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

Install GitHub CLI

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 

  gh auth login

Follow the prompts to authenticate with GitHub.

Custom System Prompt

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

Via Dashboard

  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

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

Default Prompt

The default system prompt focuses on:

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

Environment Variables

gitlab-summary supports these environment variables:

VariableDescriptionDefault
GITLAB_URLOverride GitLab instance URLConfig file value
GITLAB_TOKENOverride stored token (not recommended)Secure storage
HOMEUser home directory (Linux/macOS)System default
USERPROFILEUser profile directory (Windows)System default

Example:

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

Security Best Practices

Token Security

✅ 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

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

“Unable to authenticate with GitLab”

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”

Solution:

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

AI analysis not working

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

See Also