Documentation

Everything you need to run Jenkinsfiles locally with Plumber — version v1.0.

Getting Started

Installation

Plumber ships as a native binary for each platform. Download the installer for your OS and run it — no additional dependencies required.

• ▸Windows — run the .exe installer, follow the wizard, launch from the Start Menu.
• ▸macOS — open the .dmg, drag Plumber to Applications. First launch: right-click → Open (one-time Gatekeeper bypass).
• ▸Linux — sudo apt install ./plumber-linux-amd64.deb, then launch from your app menu.

Quick Start

Once Plumber is running, click Open in the top bar and select a directory containing a Jenkinsfile. Plumber parses it immediately and renders the stage timeline.

Press Run (or Ctrl+R) to execute the pipeline. Stages run in order; parallel {} blocks run concurrently. Output streams live in the terminal drawer.

pipeline {
  agent any
  stages {
    stage('Build') {
      steps { sh 'go build ./...' }
    }
    stage('Test') {
      steps { sh 'go test ./...' }
    }
  }
}

Core Concepts

Pipeline Parsing

Plumber uses a purpose-built Groovy Declarative Pipeline parser written in Go. It parses the pipeline structure — stages, steps, environment blocks, parallel directives — into an internal AST, then renders the timeline before execution starts.

Parse errors appear as inline markers in the built-in editor as you type. You don't need to save the file or trigger a run to see syntax problems.

Stage Execution

Each stage runs sequentially by default. Shell steps (sh, bat, powershell) spawn real OS processes in the workspace directory. Stdout and stderr are streamed line-by-line into the terminal drawer.

Click any stage in the timeline to open its log drawer. Stage duration is shown live and updated to the final elapsed time when the stage completes.

Parallel Stages

The parallel {} directive runs branches concurrently. Plumber maps each branch to a Go goroutine, so they genuinely run in parallel on your machine.

stage('Quality Gates') {
  parallel {
    stage('Lint')     { steps { sh 'golangci-lint run' } }
    stage('Scan')     { steps { sh 'trivy fs .' } }
    stage('Coverage') { steps { sh 'go test -cover ./...' } }
  }
}

The timeline renders parallel branches side-by-side with a parallel ×N badge. Each branch has its own log drawer.

Environment Variables

Variables declared in environment {} blocks are injected into every shell step in scope. Stage-level blocks override pipeline-level ones for steps within that stage.

pipeline {
  environment {
    SERVICE_NAME = 'my-api'
    DEPLOY_ENV   = 'staging'
  }
  stages {
    stage('Deploy') {
      environment { DEPLOY_ENV = 'production' }
      steps { sh 'echo Deploying $SERVICE_NAME to $DEPLOY_ENV' }
    }
  }
}

Plumber always injects CI=true and PLUMBER=1 so your scripts can detect they're running under Plumber.

Plugin System

Marketplace

Open the Plugins window from the top bar. The marketplace pulls the top 1,000 Jenkins plugins from plugins.jenkins.io (cached for 30 minutes) and displays them in a searchable, paginated grid.

Use the search box to filter by name, description, or label. Use the category buttons to narrow to a specific ecosystem. Each card is clickable — the detail page shows the full description and a direct link to the official plugin page.

Installing Plugins

Click ⬇ INSTALL on any card. Plumber downloads the .hpi from the Jenkins update centre and imports it into the plugin registry. Installed plugins persist across workspace changes.

You can also install manually via ⊕ Import .hpi in the marketplace header — useful for internal or pre-release plugins not on the public index.

Plugin Steps

When a plugin is installed, its declared step names become available in pipeline execution. Plumber loads the plugin's Groovy shim and routes step calls through it. Steps that require a running Jenkins agent are logged and skipped gracefully.

Tool Management

Portable Tools

Settings → Environment shows every tool your pipeline might need. Plumber checks three locations in order: its own tools directory, its env bin directory, and your system PATH.

For tools marked Portable (terraform, kubectl, helm, k9s, jq, yq, gh, golangci-lint, trivy), click ⬇ Download to fetch the latest release binary into Plumber's tools directory. These tools are used by pipeline steps but never modify your system PATH.

# Tool locations
# macOS / Linux:  ~/.local/share/plumber/tools/
# Windows:        %APPDATA%\Plumber\tools\

# Both dirs are prepended to PATH for every pipeline step.

Sandbox Modes

Plumber isolates pipeline steps using the strongest sandbox available on your platform:

• ▸Linux user namespaces — unshare --user --pid. Process + PID namespace isolation, zero extra dependencies.
• ▸macOS Seatbelt — sandbox-exec. Denies writes to system paths; allows workspace and /tmp. Ships with macOS.
• ▸Windows WSL — full Linux namespace stack via WSL. Requires WSL to be installed.
• ▸Windows Job Object — Win32 Job Object for process-group tracking. No extra dependencies.
• ▸Clean environment — minimal env passthrough. Available on every platform as a fallback.

Override the detected mode in Settings → Sandbox.

Settings

General

• ▸Auto-save — save the Jenkinsfile automatically on every keystroke.
• ▸Confirm before reset — show a dialog before discarding unsaved changes on Reset.
• ▸Max log lines — cap the terminal drawer buffer to avoid memory growth on long pipelines.

Editor

• ▸Font size — editor and terminal font size in points. Default 13.
• ▸Tab size — indent width in spaces. Default 2.
• ▸Show line numbers — toggle gutter line numbers.

Environment

The Environment panel shows all tools Plumber knows about, their detected location (plumber / env / system), and install hints for missing tools. Add a tool to the required list to show a warning badge in the top bar if it's not found.

Reference

Syntax Coverage

Keyboard Shortcuts