glab-ctl

README

glab-ctl

A powerful command-line tool for GitLab group management and security auditing.

Overview

glab-ctl provides two main features:

1. Sync: Clone and update all projects from GitLab groups to your local filesystem
2. Audit: Evaluate GitLab projects against security and best-practice standards

Quick Start

Installation

# Using Go install
go install gitlab.com/rfussien/glab-ctl@latest

# Or from source
git clone https://gitlab.com/rfussien/glab-ctl.git
cd glab-ctl
go build -o glab-ctl

Initial Setup

On first run, the tool will interactively prompt for configuration:

glab-ctl sync  # Will prompt for GitLab token, SSH key, group ID, and local path

Basic Usage

# Sync all projects from a GitLab group
glab-ctl sync

# Audit a group for security and best practices
glab-ctl audit -g 12345 -f markdown -o report.md

# Manage configuration
glab-ctl config get
glab-ctl config set private_token

Features

Sync

• 🔄 Pull mode with automatic updates
• 📁 Maintains GitLab namespace structure locally
• 🚫 Skips archived projects automatically
• ⚡ Concurrent cloning (10 workers)
• 🔁 Smart retry logic for failed operations
• 🗑️ Prune stale local repos with --prune (prompts before each deletion)

Audit

• 🔍 60+ automated checks across 8 domains
• 📊 Weighted scoring system (0-100)
• 🎯 Implements 16 OpenSSF SCM best practices
• 🔒 Security scanning verification
• 📈 Multiple output formats (JSON, Markdown, Table)
• ⚡ Concurrent auditing (configurable workers)
• 🚪 Hard gates for critical security issues

Audit Domains

Domain	Checks	Focus
AI	2	AI assistant context files (CLAUDE.md, AGENTS.md, .cursor/rules/, …)
Metadata	7	Documentation, README, LICENSE, topics
Governance	7	CODEOWNERS, maintainers, webhooks, activity
Merge Controls	18	Branch protection, code review, approvals
CI/CD	6	Pipeline config, templates, variables
Security	13	SAST, dependency scanning, vulnerabilities
Hygiene	5	Stale branches, unused features, activity
Standardization	6	Conventional commits, templates, labels

Documentation

Getting Started

• Installation - Installation methods and prerequisites
• Configuration - Setup and credential management

Commands

• Sync Command - Synchronize GitLab groups to local filesystem
• Audit Command - Security and best-practice auditing
• Config Command - Configuration management
• Update Command - Self-update to the latest release

Reference

• Architecture - Technical design and structure
• Development - Building, testing, and contributing
• Troubleshooting - Common issues and solutions

Examples

Sync Examples

# Sync all projects from configured group
glab-ctl sync

# Sync a specific group (one-time override)
glab-ctl sync -g 12345

# Sync and remove local repos deleted on GitLab
glab-ctl sync --prune

Update Examples

# Update to the latest release
glab-ctl update

# Check current version
glab-ctl version

Audit Examples

# Basic group audit with table output
glab-ctl audit -g 12345 -f table

# Audit with strict security requirements
glab-ctl audit -g 12345 --fail-on critical --min-score 80

# Comprehensive audit with Markdown report
glab-ctl audit -g 12345 \
  --include-subgroups \
  --fail-on medium \
  --min-score 75 \
  -f markdown \
  -o compliance-report.md

# Audit a single project
glab-ctl audit -p 67890 -f json

Requirements

• Go 1.26 or higher
• GitLab account with API access
• GitLab Personal Access Token with api scope (Owner-level role required for audit)
• SSH key configured for GitLab (only required for sync)

Configuration

Configuration is stored in ~/.config/glab-ctl/config.yaml (mode 0600):

private_token: "your-gitlab-token"
ssh_private_key: "/path/to/your/ssh/key"
root_group_id: "12345"
source_path: "/path/to/local/repos"

Setting the GITLAB_TOKEN environment variable overrides private_token — useful for CI runs and secret-manager workflows (1Password CLI, pass, direnv).

See Configuration Guide for details.

Project Structure

Projects are synchronized to match GitLab's namespace structure:

~/src/gitlab.com/
├── group-name/
│   ├── project1/
│   ├── project2/
│   └── subgroup/
│       ├── project3/
│       └── project4/

CI/CD Integration

The audit command provides exit codes for CI/CD pipelines:

audit:
  stage: compliance
  variables:
    GITLAB_TOKEN: $GITLAB_TOKEN  # CI/CD masked variable, owner-level scope
  script:
    - glab-ctl audit -g $CI_PROJECT_NAMESPACE_ID \
        -f markdown \
        -o audit-report.md \
        --fail-on high \
        --min-score 70
  artifacts:
    paths:
      - audit-report.md
    when: always
  only:
    - schedules

OpenSSF Compliance

glab-ctl audit implements 16 OpenSSF SCM best practices for GitLab, including:

• Default branch protection and force-push prevention
• Required code review with minimum two approvers
• Pipeline success requirements
• Signed commit verification
• Limited ownership (fewer than 3 owners)
• Webhook SSL verification
• And more...

See Audit Command Documentation for the complete list.

Contributing

Contributions are welcome! Please see:

• Development Guide for building and testing
• Architecture for technical design details

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Repository: gitlab.com/rfussien/glab-ctl
• Documentation: docs/
• Issues: GitLab Issues