GitHub - divmora/gitlab-fleet-governor: Declarative policy-as-code tool for governing large-scale Gitlab instances. Validate, dry-run, and enforce push rules, protected branches, compliance frameworks, and more across your entire fleet.

Production-grade, declarative policy-as-code and governance automation engine in Go for GitLab fleets.

Try the GitLab Fleet Governor Live Studio & Simulator directly in your browser.

Live Studio • Features • Quickstart • CLI Usage • Policy Reference • Operations Suite • Roadmap • AWS Lambda • CI/CD Integration • LLM Docs • Ask DeepWiki

🚀 Overview

Managing security baselines, branch protections, push rules, and compliance standards across thousands of repositories in large GitLab organizations is tedious, error-prone, and prone to configuration drift.

GitLab Fleet Governor (gitlab-fleet-governor) is a modern policy engine written in Go that treats GitLab organization governance as version-controlled code. It enables platform, security, and DevSecOps teams to:

Discover: Traverse group hierarchies using recursive BFS and match projects using rich multi-filter criteria.
Diff ($S_D \ominus S_L$): Simulate policy changes and inspect attribute-level drift in dry-run mode before mutating resources.
Enforce: Idempotently apply governance rules with bounded worker concurrency, token-bucket rate limiting, and exponential retry backoff.
Deploy Anywhere: Run as a standalone CLI tool, in CI/CD pipelines (GitLab CI, GitHub Actions), in Docker containers, or serverless in AWS Lambda.

🌟 Key Features

📜 Declarative Policy-as-Code: Author policies in interchangeable YAML or JSON with ${ENV_VAR:-default} substitution.
🌳 Fleet-Scale Discovery: Recursive Breadth-First Search (BFS) group hierarchy traversal with cycle detection and project filter pipelines.
🛡️ 11 Complete Governance Reconcilers:
1. Push Rules: Author emails, branch regexes, commit message format, file size limits, secret prevention, signed commits, and DCO sign-offs.
2. Protected Branches: Push/merge/unprotect access tiers, force push bans, code owner approvals.
3. MR Approval Rules: Global approval settings, named multi-approver matrices, username/group resolution.
4. Project Settings: Squash policies, merge methods, discussion resolution gates, artifact retention.
5. Target Branch Rules: MR branch workflow routing, wildcard pattern matching (, feat/), and unmanaged rule pruning.
6. Pipeline Retention: Automated GitLab pipeline history deletion (retention_days converted to ci_delete_pipelines_in_seconds).
7. CI/CD Variables: Scoped environment variables, masked secrets, protected flags, raw values, drift pruning.
8. Runner Governance: Shared/group runner toggles, tag enforcement, pause/locked controls.
9. Compliance Frameworks: Automated assignment of compliance framework labels (SOC2, PCI-DSS, ISO27001).
10. Webhooks & Integrations: Organization webhook endpoint provisioning, trigger filters, HMAC secret tokens, SSL verification.
11. Member & Access Audit: Over-privileged user detection, mandatory expiration dates, inherited maintainer deduplication.
⚡ High Resilience & Concurrency: Bounded worker pool, token-bucket rate limiting, reactive 429 backoff with full jitter, keyset streaming pagination.
🔍 Fleet-Wide Compliance & Security Auditing: Dedicated non-mutating audit command inspecting user access expiration hygiene, protected branch security posture, and protected environment deployment approval gates.
📑 Multi-Sheet Excel (.xlsx) & Headless SMTP Dispatch: Generates executive workbooks with auto-filtered sheets, contiguous row merging, and semantic color badges, with optional direct TLS / STARTTLS email delivery.
☁️ Dual Runtime & AWS Lambda: Auto-detects AWS_LAMBDA_FUNCTION_NAME and handles EventBridge cron, S3 Put Object, and direct JSON events.
📊 Multi-Format Summary Reports: ASCII terminal tables, structured JSON, CSV, and Markdown audit reports.

⚡ Quickstart

Step 1: Install `gitlab-fleet-governor`

# Via Go 1.26+
go install github.com/divmora/gitlab-fleet-governor/cmd/gitlab-fleet-governor@latest

# Or download pre-built binary from GitHub Releases
curl -sSL "https://github.com/divmora/gitlab-fleet-governor/releases/latest/download/gitlab-fleet-governor_Linux_x86_64.tar.gz" | tar -xz
sudo mv gitlab-fleet-governor /usr/local/bin/

Step 2: Configure Environment Variables

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export GITLAB_BASE_URL="https://gitlab.com/api/v4" # Or your self-managed URL

Step 3: Run Validation & Dry-Run Simulation

# Validate policy syntax
gitlab-fleet-governor validate -c examples/minimal.yaml

# Run dry-run simulation
gitlab-fleet-governor run -c examples/minimal.yaml --dry-run

🛠️ CLI Usage Reference

Global Flags

Flag	Short	Default	Description
`--config`	`-c`	`""`	Path to policy file, `-` for stdin, or `s3://bucket/key`
`--dry-run`		`true`	Simulation mode (preview changes without mutating state)
`--concurrency`		`10`	Number of parallel worker goroutines
`--log-level`		`"info"`	Log level (`debug`, `info`, `warn`, `error`)
`--log-format`		`"text"`	Log format (`text` or `json`)
`--report-format`		`"table"`	Report format (`table`, `json`, `csv`, `markdown`)
`--output-file`		`""`	File path to write summary report
`--no-color`		`false`	Disable terminal color output

Subcommands

`run`

Executes fleet governance reconciliation:

# Dry-run preview
gitlab-fleet-governor run -c policies/enterprise.yaml

# Apply mutations live
gitlab-fleet-governor run -c policies/enterprise.yaml --dry-run=false

# Output Markdown report to file
gitlab-fleet-governor run -c policies/enterprise.yaml --report-format markdown --output-file report.md

`export`

Reverse-syncs the live configuration of a target group or project hierarchy into a normalized policy.yaml baseline:

# Export live configuration of a group hierarchy (using default archetype strategy)
gitlab-fleet-governor export --group-path "enterprise-fleet" --recursive --output baseline-policy.yaml

# Export using an authoritative "golden template" archetype project
gitlab-fleet-governor export --group-path "enterprise-fleet" --from-project "enterprise-fleet/golden-service" --output baseline.yaml

# Export consensus-only baseline (omits divergent settings so immediate dry-runs report zero drift)
gitlab-fleet-governor export --group-path "enterprise-fleet" --strategy consensus --output consensus-policy.yaml

# Strict export: fail immediately if fleet projects have configuration drift
gitlab-fleet-governor export --group-path "enterprise-fleet" --strategy strict --output baseline.yaml

# Export a single project directly (optimized direct fetch)
gitlab-fleet-governor export --project-id 42 --output project-42-policy.yaml

# Export to stdout (pipe to file)
gitlab-fleet-governor export --group-path "platform/services" --recursive --output -

Flag	Default	Description
`--group-path`	`""`	Target GitLab group path for hierarchy inspection
`--project-id`	`0`	Target single GitLab project ID for direct inspection
`--strategy`	`archetype`	Divergence strategy: `archetype` (golden template), `consensus` (zero-drift intersection), or `strict` (fail on drift)
`--from-project`	`""`	Authoritative archetype project ID or path for `archetype` strategy
`--recursive`	`true`	Recursively traverse subgroup hierarchies
`--skip-reconciler`	`""`	Comma-separated reconcilers to exclude (e.g. `variables,webhooks`)
`--include-secrets-placeholder`	`true`	Replace masked/sensitive CI/CD variable values with `${VAR:-PLACEHOLDER}`
`--concurrency`	`10`	Bounded worker pool concurrency for parallel inspection
`-o, --output`	`""`	Destination file path (or `-` for stdout)

`audit`

Executes read-only fleet compliance and security audits with multi-sheet Excel reports and optional email distribution:

# Terminal summary audit
gitlab-fleet-governor audit -c policies/enterprise.yaml

# Generate an executive multi-sheet Excel workbook (.xlsx)
gitlab-fleet-governor audit -c policies/enterprise.yaml -o fleet-audit.xlsx --concurrency=20

# Run specific modules and export to structured JSON
gitlab-fleet-governor audit -c policies/enterprise.yaml --modules=user_access,protected_branches --format=json -o audit.json

# Audit fleet and automatically email the .xlsx report via SMTP
gitlab-fleet-governor audit -c policies/enterprise.yaml -o fleet-audit.xlsx \
  --smtp-host=smtp.mailgun.org --smtp-port=587 \
  --smtp-username=postmaster@example.com --smtp-password=secret \
  --smtp-from=security@example.com --smtp-to=compliance-team@example.com \
  --smtp-cc=ciso@example.com

`validate`

Validates configuration schema, regular expressions, and permissions without remote API calls:

gitlab-fleet-governor validate -c policies/enterprise.yaml

`lambda`

Emulates local AWS Lambda invocation with a JSON event payload:

gitlab-fleet-governor lambda --event examples/lambda-event.json

`version`

Displays version, git commit, build date, Go version, and platform info:

gitlab-fleet-governor version
gitlab-fleet-governor version --json

📋 Declarative Policy Reference

Policies are authored in YAML or JSON:

version: "v1"

settings:
  dry_run: true
  concurrency: 12
  log_level: "info"
  report_format: "table"

targets:
  group_selector:
    group_paths_include: ["enterprise-fleet"]
    recursive: true
  project_selector:
    archived: false
    visibility: "private"

policies:
  push_rules:
    author_email_regex: '@enterprise\.com$'
    prevent_secrets: true
    reject_unsigned_commits: true
    max_file_size: 20

  protected_branches:
    - name: "main"
      allowed_to_push:
        - access_level: 0
      allowed_to_merge:
        - access_level: 40
      code_owner_approval_required: true

  pipeline_retention:
    retention_days: 30

See Configuration Reference for full schema documentation.

🧩 Governance Operations Suite

 1. push_rules           Enforce commit & push policies (author regex, file size, secrets, GPG/DCO)
 2. protected_branches   Branch protection tiers, merge/push access levels, code owners
 3. approval_rules       Merge request approval settings & named reviewer matrices
 4. project_settings     Merge strategies, squash settings, discussion resolution gates
 5. target_branch_rules  MR branch workflow target branch mapping based on branch pattern
 6. pipeline_retention   Automated pipeline history cleanup (retention_days -> ci_delete_pipelines_in_seconds)
 7. variables            Scoped CI/CD variables, masked secrets, protected flags, drift pruning
 8. runners              Shared & group runner controls, maintenance pause/lock status, tags
 9. compliance           Compliance framework labeling (SOC2, PCI-DSS, ISO27001)
10. webhooks             Fleet-wide security and audit webhook integrations
11. members              Access level ceilings, mandatory expiration dates, over-privileged detection

🚀 Cloud-Native Deployments

Ready-to-use deployment manifests and cloud infrastructure templates are available:

Kubernetes CronJobs: Automated compliance audit (cronjob-audit.yaml) and governance enforcement (cronjob-enforce.yaml) CronJobs with non-root security hardening, read-only root filesystem, ConfigMap mounts, and Kustomize integration.
AWS Lambda Serverless (CloudFormation): Production CloudFormation template (lambda.yaml) for serverless execution triggered by EventBridge cron schedules or S3 policy uploads.
AWS ECS Fargate Scheduled Tasks (CloudFormation): Production CloudFormation template (ecs-fargate.yaml) for scheduled container tasks on Fargate for large enterprise fleets (>1,000 repositories) where scans require more than Lambda's 15-minute limit.

☁️ AWS Lambda & Serverless

GitLab Fleet Governor auto-detects AWS Lambda when AWS_LAMBDA_FUNCTION_NAME is set. It natively supports:

EventBridge Scheduled Cron: Run periodic audits every hour.
S3 Put Object Triggers: Reactively enforce policies whenever a policy YAML is uploaded to S3.
Direct JSON Invocations: Execute ad-hoc targeted scans.

See AWS Lambda Guide for deployment details.

IAM Least-Privilege Policy

When deploying GitLab Fleet Governor on AWS Lambda, attach the following minimal IAM execution policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyBucketAccess",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::<your-governance-bucket>",
        "arn:aws:s3:::<your-governance-bucket>/*"
      ]
    },
    {
      "Sid": "CloudWatchLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:*"
    }
  ]
}

🔄 CI/CD Pipeline Integration

Easily integrate into GitLab CI (.gitlab-ci.yml) or GitHub Actions:

# GitHub Actions Example
- name: Run Fleet Governor Dry-Run
  uses: docker://ghcr.io/divmora/gitlab-fleet-governor:latest
  env:
    GITLAB_TOKEN: ${{ secrets.GITLAB_ADMIN_TOKEN }}
  with:
    args: run -c policies/enterprise.yaml --dry-run

See CI/CD Integration Guide for full workflows.

💻 Development & Building

Prerequisites

Go: Version 1.26 or higher
Make: Build automation
golangci-lint: Static code analysis (v1.60+)
Docker: For containerized and multi-architecture builds

Common Build Targets

# Compile local host binary into bin/gitlab-fleet-governor
make build

# Run unit & integration tests with race detector and coverage
make test

# Format source code
make fmt

# Static analysis and linting
make lint

# Compile AWS Lambda custom runtime bootstrap bundle
make build-lambda

# Build local Docker image
make docker-build

🤝 Community & Contributing

Contributions are welcome!

ROADMAP.md: Living product roadmap tracking planned capabilities and architectural initiatives.
CONTRIBUTING.md: Local developer setup, make targets, and PR workflow.
CODE_OF_CONDUCT.md: Community participation standards.
SECURITY.md: Vulnerability disclosure policy and reporting process.

📄 License & Commercial Use

This project is licensed under the Business Source License 1.1 (BSL 1.1).

Non-Production Use: Free of charge for local development, staging, QA, testing, CI/CD automated validation (dry-run linting), educational purposes, and proof-of-concept evaluation.
Production Use (Free Fleet Tier): Free of charge in production environments governing a cumulative fleet size of up to twenty-five (25) managed GitLab projects/repositories at any given time.
Enterprise / Fleet Scale: Any production deployment governing more than twenty-five (25) managed projects/repositories or utilizing Enterprise-gated capabilities requires an active commercial subscription (EULA) from DIVMORA Technologies.
Change Date: Converts automatically to Apache License 2.0 three (3) years after the release date of the specific version.

For commercial inquiries and enterprise licensing, please contact licensing@divmora.com or visit divmora.com. See LICENSE and DIVMORA Licensing Policy for full terms.

📊 Subscription Tiers & Licensing Overview

Tier	Fleet Capacity	Key Capabilities	Commercial Requirement
Free Community	Up to 25 Projects	Push rules, protected branches, project settings, CI/CD variables, member audit	Zero cost (BSL 1.1)
Pro	Extended Fleet Quotas	Everything in Community + MR approval rules, MR target branch rules, runners, webhooks, pipeline retention	Active commercial license
Enterprise	Unlimited Scale	Everything in Pro + Compliance & Security Audit Suite (.xlsx + SMTP dispatch), compliance frameworks, AWS Lambda runtime	Active commercial license

Tip

Simulation Before Mutation: Dry-run simulation mode (--dry-run or settings.dry_run: true) is always 100% free and unrestricted across all tiers and fleet sizes without requiring a license key.

Community Zero-Check Bypass: When policies exercise only Community Tier capabilities, GitLab Fleet Governor bypasses all license verification completely.

👉 For the comprehensive feature entitlement matrix, tier philosophy, and enforcement details, see Subscription Plans & Feature Matrix.

Commercial License Management with `license-cli`

For inspecting commercial licenses, generating air-gapped node requests, or validating quota cards across multi-product environments, operators and customers can install the official multi-product CLI:

go install github.com/divmora/license-go/cmd/license-cli@v1.3.1

Common Operator Commands

Inspect License Claims & Scopes:

license-cli inspect -license /path/to/license.key

Verify License with Offline Revocation List (CRL):

license-cli verify -license /path/to/license.key -crl /path/to/crl.divcrl

View Live Status Card & Fleet Quota:

license-cli status -license /path/to/license.key -usage "max_projects=42"

Generate Air-Gapped Offline License Request (.divreq):

license-cli request -product "gitlab-fleet-governor" -customer "Acme Corp" -out ./node.divreq

Native Governor License Commands:

# Check active license tier and capacity in the current environment
gitlab-fleet-governor license status

# Output structured JSON for monitoring and alerts
gitlab-fleet-governor license status --json

# Headless compliance check for automated scripts and CI pipelines (exit code 0 if compliant)
gitlab-fleet-governor license check

# Display hardware and cloud environment fingerprint for node-locked licensing
gitlab-fleet-governor license fingerprint

# Output only the primary fingerprint ID (useful for license provisioning and scripts)
gitlab-fleet-governor license fingerprint -q

Name		Name	Last commit message	Last commit date
.github		.github
cmd/gitlab-fleet-governor		cmd/gitlab-fleet-governor
deploy		deploy
docs		docs
examples		examples
internal		internal
pkg/version		pkg/version
scripts		scripts
test		test
ui		ui
.dockerignore		.dockerignore
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
.release-please-config.json		.release-please-config.json
.release-please-manifest.json		.release-please-manifest.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.lambda		Dockerfile.lambda
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum

Navigation Menu

Repository navigation

About

Repository files navigation

🚀 Overview

🌟 Key Features

⚡ Quickstart

Step 1: Install `gitlab-fleet-governor`

Step 2: Configure Environment Variables

Step 3: Run Validation & Dry-Run Simulation

🛠️ CLI Usage Reference

Global Flags

Subcommands

`run`

`export`

`audit`

`validate`

`lambda`

`version`

📋 Declarative Policy Reference

🧩 Governance Operations Suite

🚀 Cloud-Native Deployments

☁️ AWS Lambda & Serverless

IAM Least-Privilege Policy

🔄 CI/CD Pipeline Integration

💻 Development & Building

Prerequisites

Common Build Targets

🤝 Community & Contributing

📄 License & Commercial Use

📊 Subscription Tiers & Licensing Overview

Commercial License Management with `license-cli`

Common Operator Commands

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🚀 Overview

🌟 Key Features

⚡ Quickstart

Step 1: Install gitlab-fleet-governor

Step 2: Configure Environment Variables

Step 3: Run Validation & Dry-Run Simulation

🛠️ CLI Usage Reference

Global Flags

Subcommands

run

export

audit

validate

lambda

version

📋 Declarative Policy Reference

🧩 Governance Operations Suite

🚀 Cloud-Native Deployments

☁️ AWS Lambda & Serverless

IAM Least-Privilege Policy

🔄 CI/CD Pipeline Integration

💻 Development & Building

Prerequisites

Common Build Targets

🤝 Community & Contributing

📄 License & Commercial Use

📊 Subscription Tiers & Licensing Overview

Commercial License Management with license-cli

Common Operator Commands

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Step 1: Install `gitlab-fleet-governor`

`run`

`export`

`audit`

`validate`

`lambda`

`version`

Commercial License Management with `license-cli`