URL Commands

Configure the GitLab instance URL for gitlab-summary to connect to.

Overview

gitlab-summary needs to know which GitLab instance to connect to. This can be:

  • GitLab.com: https://gitlab.com
  • Self-hosted: https://gitlab.company.com
  • Internal: https://git.internal.corp

url set

Set or update the GitLab instance URL.

Usage 

  gitlab-summary url set --url <URL>

Options

OptionAliasDescriptionRequired
--url-uGitLab instance URLYes

Examples

GitLab.com:

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

Self-hosted instance:

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

Internal instance with custom port:

  gitlab-summary url set --url https://git.internal.corp:8443

IP address:

  gitlab-summary url set --url http://192.168.1.100

Output 

  GitLab URL set to: https://gitlab.company.com

url show

Display the currently configured GitLab URL.

Usage 

  gitlab-summary url show

Output 

  GitLab URL: https://gitlab.company.com

Examples

Verify configuration:

  gitlab-summary url show

Use in scripts:

  CURRENT_URL=$(gitlab-summary url show | grep "GitLab URL:" | cut -d' ' -f3)
echo "Currently configured: $CURRENT_URL"

Configuration Storage

Settings File Location

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

File Format 

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

Manual Editing

You can edit this file directly:

  # macOS/Linux
nano ~/.gitlab-summary/settings.json

# Windows
notepad %USERPROFILE%\.gitlab-summary\settings.json

Restart required: Changes take effect on next command

URL Override

Per-Command Override

Override the configured URL for a single command:

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

Use Cases:

  • Testing different GitLab instances
  • One-time queries
  • Multi-instance monitoring

Environment Variable Override 

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

Precedence:

  1. --url flag (highest)
  2. GITLAB_URL environment variable
  3. Settings file value (lowest)

URL Format

Required Format

  • Must be a valid HTTP(S) URL
  • Include protocol (http:// or https://)
  • No trailing slash

Valid Examples

✅ https://gitlab.com
✅ https://gitlab.company.com
✅ https://git.internal.corp:8443
✅ http://192.168.1.100
✅ http://localhost:8080

Invalid Examples

❌ gitlab.com (missing protocol)
❌ https://gitlab.com/ (trailing slash)
❌ gitlab.company.com (missing protocol)

Common Scenarios

Scenario 1: Initial Setup 

  # Set URL
gitlab-summary url set --url https://gitlab.company.com

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

# Test
gitlab-summary pipelines --group test --since 1h

Scenario 2: Switching Instances 

  # Switch from GitLab.com to self-hosted
gitlab-summary url set --url https://gitlab.company.com

# Update token for new instance
gitlab-summary token clear
gitlab-summary token set --url https://gitlab.company.com

Scenario 3: Multi-Instance Monitoring

Option A: Use –url flag

  # Monitor instance 1
gitlab-summary pipelines --group team1 --url https://gitlab1.com

# Monitor instance 2
gitlab-summary pipelines --group team2 --url https://gitlab2.com

Option B: Create shell functions

  # Add to ~/.bashrc or ~/.zshrc

gitlab-summary-prod() {
  gitlab-summary "$@" --url https://gitlab.prod.com
}

gitlab-summary-staging() {
  gitlab-summary "$@" --url https://gitlab.staging.com
}

# Usage
gitlab-summary-prod pipelines --group my-org
gitlab-summary-staging pipelines --group my-org

Scenario 4: Development Setup 

  # Local GitLab instance
gitlab-summary url set --url http://localhost:8080

# With specific port
gitlab-summary url set --url http://localhost:8929

SSL/TLS Considerations

Self-Signed Certificates

If your GitLab instance uses self-signed certificates, you may need to configure certificate validation.

Current Limitation: gitlab-summary validates SSL certificates by default.

Workaround for development:

  # Use HTTP instead of HTTPS (if available)
gitlab-summary url set --url http://gitlab.internal.corp

Production Solution: Install proper SSL certificates on GitLab instance

Certificate Errors

Symptom: SSL/TLS errors when connecting

Causes:

  • Expired certificate
  • Self-signed certificate
  • Certificate name mismatch

Solutions:

  1. Ensure certificate is valid and trusted
  2. Install CA certificate if self-signed
  3. Use HTTP for local development only

Troubleshooting

“Connection refused”

Causes:

  • Wrong URL
  • GitLab instance down
  • Network/firewall blocking

Solutions:

  # Test connectivity
curl https://gitlab.company.com

# Verify URL
gitlab-summary url show

# Try with correct URL
gitlab-summary url set --url https://correct-url.com

“Invalid URL format”

Causes:

  • Missing protocol
  • Trailing slash
  • Invalid characters

Solutions:

  # ❌ Wrong
gitlab-summary url set --url gitlab.com
gitlab-summary url set --url https://gitlab.com/

# ✅ Correct
gitlab-summary url set --url https://gitlab.com

Commands use wrong GitLab instance

Causes:

  • Environment variable override
  • Outdated settings file

Solutions:

  # Check for environment variable
env | grep GITLAB_URL

# Unset if present
unset GITLAB_URL

# Verify settings
gitlab-summary url show

# Reset if needed
gitlab-summary url set --url https://correct-url.com

API Endpoint Construction

gitlab-summary constructs GitLab API URLs as:

  {GitLabUrl}/api/v4/{endpoint}

Examples:

Configured URLAPI Endpoint
https://gitlab.comhttps://gitlab.com/api/v4/groups
https://gitlab.company.comhttps://gitlab.company.com/api/v4/groups
http://localhost:8080http://localhost:8080/api/v4/groups

Security Notes

HTTPS vs HTTP

Production: Always use HTTPS

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

Development Only: HTTP acceptable for localhost

  gitlab-summary url set --url http://localhost:8080

URL in Serve Mode

When running dashboard server, the GitLab URL is exposed via API:

  curl http://localhost:5100/api/settings

Response includes:

  {
  "group": "my-org",
  "since": "7d",
  "gitlabUrl": "https://gitlab.company.com"
}

Note: URL is not sensitive, but confirms your GitLab instance

Examples by GitLab Type

GitLab.com (SaaS) 

  gitlab-summary url set --url https://gitlab.com
gitlab-summary token set --url https://gitlab.com
gitlab-summary pipelines --group my-public-group

GitLab Self-Managed (On-Premises) 

  gitlab-summary url set --url https://gitlab.internal.company.com
gitlab-summary token set --url https://gitlab.internal.company.com
gitlab-summary serve --group engineering --open

GitLab in Docker (Local Development) 

  # Start GitLab container
docker run -d -p 8080:80 gitlab/gitlab-ce:latest

# Configure gitlab-summary
gitlab-summary url set --url http://localhost:8080

# Wait for GitLab to start (can take several minutes)
# Then set token and use normally

Integration with Token Commands

URL and token are configured separately but work together:

Typical Workflow 

  # 1. Set URL
gitlab-summary url set --url https://gitlab.company.com

# 2. Set token (uses the URL)
gitlab-summary token set --url https://gitlab.company.com

# 3. Verify both
gitlab-summary url show
gitlab-summary token show

# 4. Test connection
gitlab-summary pipelines --group test --since 1h

When Switching Instances 

  # Switching to different GitLab instance

# Clear old token
gitlab-summary token clear

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

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

See Also