Token Commands

Secure token storage and management for GitLab authentication.

Overview

gitlab-summary stores GitLab access tokens securely using platform-specific APIs:

  • macOS: Keychain
  • Windows: DPAPI (Data Protection API)
  • Linux: .NET DataProtection with file-based storage

token set

Store or update your GitLab access token.

Usage 

  gitlab-summary token set --url <URL>

Options

OptionAliasDescriptionRequired
--url-uGitLab instance URLYes
  gitlab-summary token set --url https://gitlab.example.com

Prompt:

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

Security: Token input is masked (not visible on screen)

Non-Interactive Mode

For automation or scripts:

  echo "glpat-xxxxxxxxxxxxxxxxxxxx" | gitlab-summary token set --url https://gitlab.example.com

⚠️ Warning: Avoid hardcoding tokens in scripts. Use environment variables or secret management tools.

Examples

Basic usage:

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

Self-hosted GitLab:

  gitlab-summary token set --url https://git.internal.company.net

From environment variable:

  echo "$GITLAB_TOKEN" | gitlab-summary token set --url https://gitlab.example.com

token show

Display the stored token (masked) and configured GitLab URL.

Usage 

  gitlab-summary token show

Output 

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

Security: Only shows first/last few characters

Examples

Verify token is stored:

  gitlab-summary token show
# Outputs token info if configured
# Exits with error if no token stored

Check in script:

  if gitlab-summary token show &>/dev/null; then
  echo "Token configured"
else
  echo "No token found"
  gitlab-summary token set --url https://gitlab.example.com
fi

token clear

Remove the stored token from secure storage.

Usage 

  gitlab-summary token clear

Output 

  Token cleared successfully.

When to Use

Rotating tokens:

  # Remove old token
gitlab-summary token clear

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

Switching GitLab instances:

  # Clear old instance token
gitlab-summary token clear

# Configure new instance
gitlab-summary token set --url https://new-gitlab.com

Security cleanup:

  # Before decommissioning machine
gitlab-summary token clear

Examples

Safe rotation script:

  #!/bin/bash
# Rotate GitLab token safely

# Clear existing token
gitlab-summary token clear

# Prompt for new token
gitlab-summary token set --url https://gitlab.example.com

# Verify it works
gitlab-summary pipelines --group test-group --since 1h

Token Storage Locations

macOS

Keychain Access:

  • Service: gitlab-summary
  • Account: gitlab-token

View manually:

  1. Open Keychain Access app
  2. Search for “gitlab-summary”
  3. View attributes (password remains encrypted)

Delete manually:

  security delete-generic-password -s "gitlab-summary" -a "gitlab-token"

Windows

DPAPI protected file:

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

Delete manually:

  Remove-Item "$env:USERPROFILE\.gitlab-summary\protected-token.dat"

Linux

.NET DataProtection:

  • Token: ~/.gitlab-summary/protected-token.dat
  • Keys: ~/.microsoft/usersecrets/

Permissions:

  # Token file (read/write owner only)
-rw------- 1 user user  256 Feb  8 10:00 protected-token.dat

Delete manually:

  rm ~/.gitlab-summary/protected-token.dat

Creating GitLab Tokens

Personal Access Token

  1. Log in to GitLab
  2. User Settings → Access Tokens
  3. Create token:
    • Name: gitlab-summary
    • Scopes: read_api (only)
    • Expiration: Based on policy
  4. Copy token (only shown once)
  5. Store in gitlab-summary:
      gitlab-summary token set --url https://gitlab.example.com

Group Access Token

For team/shared dashboards:

  1. Navigate to group in GitLab
  2. Settings → Access Tokens
  3. Create token:
    • Name: gitlab-summary-team
    • Role: Reporter or higher
    • Scopes: read_api
  4. Copy token
  5. Store securely (consider secrets manager for shared systems)

Token Security Best Practices

✅ DO

  • Use minimal scopes (read_api only)
  • Set expiration dates (rotate regularly)
  • Use group tokens for shared systems
  • Store via CLI (uses secure storage)
  • Rotate compromised tokens immediately

❌ DON’T

  • Commit to version control
  • Share tokens between users
  • Use write scopes (unnecessary)
  • Store in plain text files
  • Log or print tokens

Example: Secure Team Setup 

  # DON'T: Share token directly
echo "Here's the token: glpat-xxx" | slack send

# DO: Share setup instructions
cat << 'EOF' | slack send
Setup instructions:
1. Create your own token: https://gitlab.com/-/profile/personal_access_tokens
2. Scope: read_api only
3. Run: gitlab-summary token set --url https://gitlab.example.com
EOF

Troubleshooting

“Token not found”

Symptom: Commands fail with authentication error

Solution:

  # Check if token is stored
gitlab-summary token show

# If not stored, set it
gitlab-summary token set --url https://gitlab.example.com

“Invalid token”

Causes:

  • Token expired
  • Token revoked
  • Wrong GitLab URL

Solution:

  # Clear and reset
gitlab-summary token clear
gitlab-summary token set --url https://gitlab.example.com

# Verify with GitLab API
curl -H "PRIVATE-TOKEN: your-token" https://gitlab.example.com/api/v4/user

Permission denied (Linux/macOS)

Symptom: Cannot read/write token file

Solution:

  # Fix directory permissions
chmod 700 ~/.gitlab-summary

# Fix file permissions
chmod 600 ~/.gitlab-summary/protected-token.dat

Token works in curl but not gitlab-summary

Causes:

  • Different URL configured
  • Token not stored via CLI

Solution:

  # Verify URL matches
gitlab-summary url show
# Should match your curl URL

# Re-store token
gitlab-summary token clear
gitlab-summary token set --url https://correct-gitlab-url.com

Environment Variables

Override Stored Token

Not recommended, but possible for testing:

  export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
gitlab-summary pipelines --group my-org

Better approach: Use proper token storage

Override URL 

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

See Also