Group Navigation

gitlab-summary provides powerful tools for navigating complex GitLab group hierarchies, making it easy to switch between groups and explore organizational structures.

Quick Group Change

Input Field Method

The simplest way to change groups:

  1. Locate input field in the top bar (shows current group)
  2. Clear existing value
  3. Type new group ID or path
  4. Press Enter

Accepts:

  • Group ID (numeric): 2217
  • Group path: my-org
  • Full path with parent: parent-org/my-org

What Happens:

  • Dashboard immediately switches to new group
  • All data refreshes
  • Time period selection persists

Group Hierarchy Browser

For complex organizations with nested groups, use the visual tree browser.

📸 Screenshot placeholder: dashboard-group-selector.png Description: Group hierarchy browser dialog showing current group highlighted at top, parent group section, sibling groups list, and child subgroups expandable tree

Opening the Browser

Click the tree icon (📁) next to the group input field

Browser Layout

The dialog shows four sections:

1. Current Group (Highlighted)

  • The group you’re currently viewing
  • Displayed at the top with highlight color
  • Shows group name and ID

2. Parent Group

Displayed if current group has a parent

Shows:

  • Parent group name
  • Group ID
  • Path
  • Click to navigate to parent

Use Cases:

  • Navigate up the hierarchy
  • View broader organizational scope
  • Access parent-level pipelines

3. Sibling Groups

Groups at the same level as current group

Shows:

  • Other groups under same parent
  • Useful for switching between related teams
  • Sorted alphabetically

Example Structure:

  parent-org/
├── frontend-team  ← current
├── backend-team   ← sibling
└── devops-team    ← sibling

4. Child Groups (Subgroups)

Groups nested under current group

Shows:

  • Immediate children only
  • Deeper nesting shown when navigating
  • Expand to see sub-subgroups

Example Structure:

  my-org/  ← current
├── api-team      ← child
├── web-team      ← child
└── mobile-team   ← child
    ├── ios       ← grandchild (shown when you select mobile-team)
    └── android

Drilling Down

Start at top-level group:

  company/
├── engineering/
│   ├── backend/
│   │   ├── api-services/
│   │   └── data-services/
│   └── frontend/
└── operations/

Navigation Steps:

  1. Start viewing company
  2. Click engineering in child groups
  3. Click backend in child groups
  4. Click api-services in child groups

Moving Sideways

Switch between sibling groups:

  engineering/
├── backend/   ← current
├── frontend/  ← switch here
└── mobile/

Steps:

  1. Open group browser
  2. View sibling groups
  3. Click frontend

Moving Up

Navigate to parent:

  company/
└── engineering/
    └── backend/  ← current, want to go to engineering

Steps:

  1. Open group browser
  2. Click parent group (engineering)
  3. View parent’s scope

Filtering & Search

By Project

Once in correct group, filter projects:

In CLI:

  gitlab-summary pipelines --group my-org --project api

In Dashboard:

  • Use search/filter controls on Projects page
  • Type project name to filter list

By Time Range

Change time period to focus on recent activity:

Dropdown options:

  • 1 day (last 24 hours)
  • 3 days
  • 7 days (default)
  • 14 days
  • 30 days

Understanding Group Structure

Group Types

Top-Level Groups:

  • No parent
  • Organization root
  • Example: company, open-source-projects

Subgroups:

  • Nested under another group
  • Organizational subdivision
  • Example: company/engineering/backend

Finding Your Group

Not sure which group to monitor?

Method 1: GitLab URL

When viewing a group in GitLab:

  https://gitlab.example.com/groups/company/engineering/backend
                                    └────────────────────────┘
                                         group path

Method 2: Group Settings

  1. Navigate to group in GitLab
  2. Settings → General
  3. Look for “Group ID” (numeric)

Method 3: Trial and Error 

  # Try top-level group
gitlab-summary serve --group company --open

# Use browser to navigate down
# Click through child groups until you find the right one

Working with Large Organizations

Strategy for 100+ Groups

Bookmark Common Groups:

  • Note frequently-used group IDs
  • Create shell aliases
  # ~/.bashrc or ~/.zshrc
alias gls-backend='gitlab-summary serve --group 2217 --open'
alias gls-frontend='gitlab-summary serve --group 2218 --open'
alias gls-mobile='gitlab-summary serve --group 2219 --open'

Start at Team Level:

  • Don’t monitor entire organization
  • Focus on your team’s group
  • Reduces noise and load time

Use Subgroups:

  • Organize by function (api, web, mobile)
  • Organize by product (product-a, product-b)
  • Organize by environment (dev, staging, prod)

Group Access Permissions

Token Scope

Your GitLab token determines which groups you can access:

Personal Access Token:

  • Access to groups you’re a member of
  • Visibility settings apply

Group Access Token:

  • Access to specific group and subgroups
  • Recommended for team dashboards

Permission Levels

Required: Reporter or higher

  • Read access to pipelines
  • View job logs
  • Access CI/CD information

Not Required: Maintainer/Owner

  • read_api scope is sufficient
  • No write permissions needed

Dynamic Group Switching

Without Server Restart

Traditional Approach (❌):

  # Stop server
Ctrl+C

# Restart with new group
gitlab-summary serve --group different-org --open

Dynamic Approach (✅):

  # Start once
gitlab-summary serve --group my-org --open

# Change group in UI (no restart needed)
# Use input field or group browser

Benefits:

  • Faster switching
  • No connection interruption
  • Maintains browser state (theme, preferences)

API Integration

For programmatic group switching:

Get Current Settings 

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

Response:

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

Change Group 

  curl -X POST http://localhost:5100/api/settings \
  -H "Content-Type: application/json" \
  -d '{"group":"different-org","since":"7d"}'

Get Group Details 

  curl http://localhost:5100/api/groups/my-org

Get Subgroups 

  curl http://localhost:5100/api/groups/my-org/subgroups

See API Reference for complete documentation.

Troubleshooting

“Group not found”

Causes:

  • Invalid group ID or path
  • No access permission
  • Token expired

Solutions:

  # Verify group exists in GitLab UI
# Check token permissions
gitlab-summary token show

# Try with group ID instead of path
gitlab-summary serve --group 2217 --open

Empty group list in browser

Causes:

  • Group has no parent/siblings/children
  • Token lacks permissions
  • Network connectivity

Solutions:

  • Verify group structure in GitLab
  • Check API access with curl
  • Review token scopes

Slow group loading

Causes:

  • Large group structure (100+ subgroups)
  • Network latency
  • GitLab API rate limiting

Solutions:

  • Use group IDs instead of paths (faster)
  • Cache frequently-used groups locally
  • Reduce time range to speed up data fetching

Best Practices

For Small Teams (1-10 projects)

  • Monitor at team group level
  • No need for complex navigation
  • Focus on time range filtering

For Medium Teams (10-50 projects)

  • Use subgroups by function
  • Bookmark key groups
  • Utilize project filtering

For Large Organizations (50+ projects)

  • Strictly use subgroups
  • Create multiple monitoring dashboards
  • Use shell aliases for quick access
  • Consider separate tokens per department

Examples

Example 1: Microservices Organization 

  company/
└── engineering/
    ├── platform/
    │   ├── auth-service
    │   ├── user-service
    │   └── notification-service
    ├── products/
    │   ├── web-app
    │   └── mobile-app
    └── infrastructure/
        ├── terraform
        └── kubernetes

Monitoring Strategy:

  • Platform team monitors engineering/platform
  • Product team monitors engineering/products
  • DevOps monitors engineering/infrastructure
  • Leadership monitors engineering (all)

Example 2: Multi-Product Company 

  company/
├── product-alpha/
│   ├── backend/
│   ├── frontend/
│   └── mobile/
├── product-beta/
│   ├── backend/
│   └── frontend/
└── shared-services/
    ├── api-gateway
    └── logging

Monitoring Strategy:

  • Product teams monitor own product group
  • Shared services team monitors shared-services
  • Architects monitor company (all products)

See Also