plumber

README

CI/CD compliance scanner for GitLab pipelines

Website • Discord • Issues

---

🤔 What is Plumber?

Plumber is a compliance scanner for GitLab. It reads your .gitlab-ci.yml and repository settings, then checks for security and compliance issues like:

• Container images using mutable tags (latest, dev)
• Container images from untrusted registries
• Unprotected branches

How does it work? Plumber connects to your GitLab instance via API, analyzes your pipeline configuration, and reports any issues it finds. You define what's allowed in a config file (.plumber.yaml), and Plumber tells you if your project complies.

🚀 Two Ways to Use Plumber

Choose one of these methods. You don't need both:

Method	Best for	How it works
CLI	Quick evaluation, local testing, one-off scans	Install binary and run from terminal
GitLab CI Component	Automated checks on every pipeline run	Add 2 lines to your .gitlab-ci.yml

---

📖 Table of Contents

• What is Plumber?
• CLI
• GitLab CI Component
• Configuration
• Installation
• CLI Reference
• Self-Hosted GitLab
• Troubleshooting

---

Option 1: CLI

Try Plumber in 2 minutes! No commits, no CI changes, just run it.

Step 1: Install

Choose one of the following:

Homebrew

brew tap getplumber/plumber
brew install plumber

Mise

mise use -g ubi:getplumber/plumber

Direct Download

curl -LO "https://github.com/getplumber/plumber/releases/latest/download/plumber-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')"
chmod +x plumber-* && sudo mv plumber-* /usr/local/bin/plumber

📦 See Installation for Windows, Docker, or building from source.

Step 2: Generate a Config File

plumber generate config

This creates .plumber.yaml with default compliance rules. You can customize it later.

Step 3: Create & Set Your Token

1. In GitLab, go to User Settings → Access Tokens (direct link)
2. Create a Personal Access Token with read_api + read_repository scopes
3. Export it in your terminal:

export GITLAB_TOKEN=glpat-xxxx

💡 You can also use a project or group access token if you prefer scoped permissions.

Step 4: Run Analysis

plumber analyze \
  --gitlab-url https://gitlab.com \
  --project mygroup/myproject

Plumber reads your .plumber.yaml config and outputs a compliance report. You can also tell it to store the output in JSON format with the --output flag.

💡 Like what you see? Add Plumber to your CI/CD with the GitLab CI Component for automated checks on every pipeline.

---

Option 2: GitLab CI Component

Add Plumber to your GitLab pipeline: it will run automatically on the default branch, tags and open merge requests.

⚠️ These instructions are for gitlab.com. Self-hosted? See Self-Hosted GitLab.

Step 1: Create a GitLab Token

1. In GitLab, go to User Settings → Access Tokens (or create one here)
2. Create a Personal Access Token with read_api + read_repository scopes
3. Go to your project's Settings → CI/CD → Variables
4. Add the token as GITLAB_TOKEN (masked recommended)

💡 You can also use a project or group access token if you prefer scoped permissions.

Step 2: Add to Your Pipeline

Add this to your .gitlab-ci.yml:

include:
  - component: gitlab.com/getplumber/plumber/plumber@~latest

Step 3: Run Your Pipeline

That's it! Plumber will now run on every pipeline and report compliance issues.

💡 Want to customize? See Configuration to set thresholds, enable/disable controls, and whitelist trusted images.

---

⚙️ Configuration

GitLab CI Component Inputs

Override any input to fit your needs:

include:
  - component: gitlab.com/getplumber/plumber/plumber@~latest
    inputs:
      threshold: 80                           # Minimum % to pass (default: 100)
      config_file: configs/my-plumber.yaml    # Custom config path
      server_url: https://gitlab.example.com  # Self-hosted GitLab
      branch: develop                         # Specific branch to analyze
      verbose: true                           # Debug output

All available inputs

Input	Default	Description
server_url	$CI_SERVER_URL	GitLab instance URL
project_path	$CI_PROJECT_PATH	Project to analyze
branch	$CI_COMMIT_REF_NAME	Branch to analyze
gitlab_token	$GITLAB_TOKEN	GitLab API token (requires read_api + read_repository)
threshold	100	Minimum compliance % to pass
config_file	(auto-detect)	Path to config file (relative to repo root)
output_file	plumber-report.json	Path to write JSON results
print_output	true	Print text output to stdout
stage	.pre	Pipeline stage for the job
image	getplumber/plumber:0.1	Docker image to use
allow_failure	false	Allow job to fail without blocking
verbose	false	Enable debug output

Configuration File

Generate a default configuration file with:

plumber generate config

Flags:
  -f, --force           Overwrite existing file
  -o, --output string   Output file path (default ".plumber.yaml")

This creates .plumber.yaml with sensible defaults. Customize it to fit your needs:

---

📦 Installation

Homebrew

brew tap getplumber/plumber
brew install plumber

To install a specific version:

brew tap getplumber/plumber
brew install plumber@0.1.23

Mise

mise use -g ubi:getplumber/plumber

Binary Download

Linux (amd64)

curl -LO https://github.com/getplumber/plumber/releases/latest/download/plumber-linux-amd64
chmod +x plumber-linux-amd64
sudo mv plumber-linux-amd64 /usr/local/bin/plumber

Linux (arm64)

curl -LO https://github.com/getplumber/plumber/releases/latest/download/plumber-linux-arm64
chmod +x plumber-linux-arm64
sudo mv plumber-linux-arm64 /usr/local/bin/plumber

macOS (Apple Silicon)

curl -LO https://github.com/getplumber/plumber/releases/latest/download/plumber-darwin-arm64
chmod +x plumber-darwin-arm64
sudo mv plumber-darwin-arm64 /usr/local/bin/plumber

macOS (Intel)

curl -LO https://github.com/getplumber/plumber/releases/latest/download/plumber-darwin-amd64
chmod +x plumber-darwin-amd64
sudo mv plumber-darwin-amd64 /usr/local/bin/plumber

Windows (PowerShell)

Invoke-WebRequest -Uri https://github.com/getplumber/plumber/releases/latest/download/plumber-windows-amd64.exe -OutFile plumber.exe

Verify checksum

curl -LO https://github.com/getplumber/plumber/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing

Docker

docker pull getplumber/plumber:latest

docker run --rm \
  -e GITLAB_TOKEN=glpat-xxxx \
  getplumber/plumber:latest analyze \
  --gitlab-url https://your-gitlab-instance.com \ 
  --project mygroup/myproject

Build from Source

Requires Go 1.24+ and Make.

git clone https://github.com/getplumber/plumber.git
cd plumber
make build # or make install to build and copy to /usr/local/bin/

---

🔍 CLI Reference

plumber analyze

Run compliance analysis on a GitLab project.

plumber analyze [flags]

Flags

Flag	Required	Default	Description
--gitlab-url	Yes	—	GitLab instance URL
--project	Yes	—	Project path (e.g., group/project)
--config	No	.plumber.yaml	Path to config file
--threshold	No	100	Minimum compliance % to pass (0-100)
--branch	No	default	Branch to analyze
--output	No	—	Write JSON results to file
--print	No	true	Print text output to stdout

Environment Variables

Variable	Required	Description
GITLAB_TOKEN	Yes	GitLab API token with read_api + read_repository scopes

Exit Codes

Code	Meaning
0	Compliance ≥ threshold
1	Compliance < threshold or error

plumber generate config

Generate a default .plumber.yaml configuration file.

plumber generate config [flags]

Flag	Default	Description
--output, -o	.plumber.yaml	Output file path
--force, -f	false	Overwrite existing file

Examples:

# Generate default config
plumber generate config

# Custom filename
plumber generate config --output my-plumber.yaml

# Overwrite existing file
plumber generate config --force

---

⚠️ Self-Hosted GitLab

If you're running a self-hosted GitLab instance, you'll need to host your own copy of the component.

Step-by-step setup

Step 1: Import the repository

• Go to New Project → Import project → Repository by URL
• URL: https://gitlab.com/getplumber/plumber.git
• Choose a group/project name (e.g., infrastructure/plumber)

Step 2: Enable CI/CD Catalog

• Go to Settings → General
• Make sure the project has a description (required for CI/CD Catalog)
• Expand Visibility, project features, permissions
• Toggle CI/CD Catalog resource to enabled
• Click Save changes

Step 3: Create a release

• Go to Code → Tags → New tag
• Enter a version (e.g., 1.0.0)
• Click Create tag

Step 4: Create a GitLab Token

In the project you want to scan:

1. Go to User Settings → Access Tokens on your GitLab instance
2. Create a Personal Access Token with read_api + read_repository scopes
3. Go to the project's Settings → CI/CD → Variables
4. Add the token as GITLAB_TOKEN (masked recommended)

💡 You can also use a project or group access token if you prefer scoped permissions.

Step 5: Use in your pipelines

include:
  - component: gitlab.example.com/infrastructure/plumber/plumber@1.0.0

💡 Format: <your-gitlab-host>/<project-path>/plumber@<tag>

---

🔧 Troubleshooting

Issue	Solution
GITLAB_TOKEN environment variable is required	Set GITLAB_TOKEN in CI/CD Variables or export it locally
401 Unauthorized	Token needs read_api + read_repository scopes
403 Forbidden on MR settings	Expected on non-Premium GitLab; continues without that data
404 Not Found	Verify project path and GitLab URL are correct
Configuration file not found	Use absolute path in Docker, relative path otherwise

💡 Need help? Open an issue or join our Discord

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on how to submit pull requests, report issues, and coding conventions.

📄 License

Mozilla Public License 2.0 (MPL-2.0)