Installation

gitlab-summary can be installed in multiple ways depending on your needs and environment.

Prerequisites

Before installing, ensure you have:

  • GitLab Access — A GitLab instance you can access
  • Access Token — Personal or Group Access Token with read_api scope
  • Docker (for Option 1) or .NET 10 SDK (for Options 2-4 if building from source)
  • GitHub Copilot subscription (optional, for AI failure analysis)

Option 1: Docker (Easiest)

Run the dashboard with Docker in seconds. No .NET installation required.

  1. Create .env file with your tokens:
  cat > .env << EOF
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_URL=https://gitlab.example.com
GITLAB_GROUP=your-group-id
GH_TOKEN=github_pat_your_token_here
EOF
  1. Download docker-compose.yml:
  curl -O https://raw.githubusercontent.com/garrardkitchen/gitlab-summary/main/docker-compose.yml
  1. Start the dashboard:
  docker-compose up -d
  1. Access the dashboard:
  open http://localhost:5100

Using docker run

Linux/Windows - Named volume:

  docker run -d \
  --name gitlab-summary \
  -p 5100:5100 \
  -e GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx" \
  -e GITLAB_URL="https://gitlab.example.com" \
  -e GITLAB_GROUP="your-group-id" \
  -e GH_TOKEN="github_pat_your_token_here" \
  -v gitlab-summary-data:/home/ubuntu/.local/share/gitlab-summary \
  garrardkitchen/gitlab-summary:latest

macOS - Bind mount:

  docker run -d \
  --name gitlab-summary \
  -p 5100:5100 \
  -e GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx" \
  -e GITLAB_URL="https://gitlab.example.com" \
  -e GITLAB_GROUP="your-group-id" \
  -e GH_TOKEN="github_pat_your_token_here" \
  -v ~/.gitlab-summary:/home/ubuntu/.local/share/gitlab-summary \
  garrardkitchen/gitlab-summary:latest

Token Setup

GitLab Token:

  • Go to GitLab → Settings → Access Tokens
  • Create token with read_api scope
  • Format: glpat-xxxxxxxxxxxxxxxxxxxx

GitHub Token (Optional - for AI analysis):

  • Go to https://github.com/settings/tokens?type=beta
  • Create Fine-grained Personal Access Token
  • Required User permissions:
    • Copilot Chat: Read
    • User copilot requests: Read
    • Gists: Read and Write
  • Format: github_pat_xxxxxxxxxxxxxxxxxxxx

Manage the Container 

  # View logs
docker-compose logs -f

# Stop the dashboard
docker-compose down

# Restart
docker-compose restart

# Check status
docker-compose ps

📚 See the Docker Guide for production deployment, troubleshooting, and advanced configuration.

Option 2: .NET Global Tool

The easiest way to install gitlab-summary is as a .NET global tool.

Install 

  dotnet tool install -g GitLabSummary

Update

To update to the latest version:

  dotnet tool update -g GitLabSummary

Verify Installation 

  gitlab-summary --version

Uninstall 

  dotnet tool uninstall -g GitLabSummary

Option 3: Self-Contained Executables

Download pre-built executables from the Releases page. No .NET installation required.

Windows (x64) 

  # Download
curl -L -o gitlab-summary.exe https://github.com/garrardkitchen/gitlab-summary/releases/latest/download/gitlab-summary-win-x64.exe

# Run
./gitlab-summary.exe --version

macOS (Apple Silicon ARM64) 

  # Download
curl -L -o gitlab-summary https://github.com/garrardkitchen/gitlab-summary/releases/latest/download/gitlab-summary-osx-arm64

# Make executable
chmod +x gitlab-summary

# Run
./gitlab-summary --version

macOS (Intel x64) 

  # Download
curl -L -o gitlab-summary https://github.com/garrardkitchen/gitlab-summary/releases/latest/download/gitlab-summary-osx-x64

# Make executable
chmod +x gitlab-summary

# Run
./gitlab-summary --version

Linux (x64) 

  # Download
curl -L -o gitlab-summary https://github.com/garrardkitchen/gitlab-summary/releases/latest/download/gitlab-summary-linux-x64

# Make executable
chmod +x gitlab-summary

# Run
./gitlab-summary --version

Tip: Move the executable to a directory in your PATH:

  # macOS/Linux
sudo mv gitlab-summary /usr/local/bin/

# Verify
gitlab-summary --version

Option 4: Build from Source

Build from source if you want the latest development version or need to customize the build.

Clone Repository 

  git clone https://github.com/garrardkitchen/gitlab-summary.git
cd gitlab-summary

Build Dashboard 

  cd src/dashboard
npm install
npm run build

Build CLI 

  cd ../cli
dotnet build

Run 

  dotnet run --project src/cli/GitLabSummary -- --version

Optional: Create Alias

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

  alias gitlab-summary='dotnet run --project ~/path/to/gitlab-summary/src/cli/GitLabSummary --'

Verify Installation

After installation, verify everything works:

  # Check version
gitlab-summary --version

# View help
gitlab-summary --help

Expected output:

  gitlab-summary v1.0.0

System Requirements

Minimum Requirements

  • OS: Windows 10+, macOS 11+, or modern Linux
  • RAM: 256 MB
  • Disk: 100 MB for installation

For Dashboard Development

  • Node.js: 18.x or later
  • npm: 9.x or later
  • Browser: Modern browser with ES2020 support

Troubleshooting

“Command not found” after global tool install

The .NET tools directory may not be in your PATH.

Solution:

  # macOS/Linux
export PATH="$PATH:$HOME/.dotnet/tools"

# Add to ~/.bashrc or ~/.zshrc to persist
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zshrc
  
  # Windows PowerShell
$env:PATH += ";$env:USERPROFILE\.dotnet\tools"

# Add permanently via System Environment Variables

“Permission denied” on macOS/Linux executables

Solution:

  chmod +x gitlab-summary

Executable won’t run on macOS (security warning)

Solution:

  # Remove quarantine attribute
xattr -d com.apple.quarantine gitlab-summary

# Or use System Preferences → Security & Privacy → Allow

.NET SDK not found (building from source)

Solution:

Download and install .NET 10 SDK from https://dotnet.microsoft.com/download

Next Steps

Updating gitlab-summary

Global Tool 

  dotnet tool update -g GitLabSummary

Self-Contained Executable

Download the latest release and replace your existing executable.

From Source 

  cd gitlab-summary
git pull origin main
cd src/dashboard && npm install && npm run build
cd ../cli && dotnet build

See Also