Documentation

Setup, usage, and reference for Pipeline Builder. New here? Start with Getting Started below, then jump into Creating Pipelines.

Getting Started

1. Deploy — choose Local, Minikube, EC2, or Fargate
2. Register — create an admin user and organization
3. Load plugins — upload from deploy/plugins/ or create your own
4. Build pipelines — use the dashboard, CLI, API, or AI prompt

---

Key Concepts

• Pipeline — CI/CD definition composed of stages, each referencing plugins. Synthesized into AWS CDK stacks at deploy time.
• Plugin — Reusable build step packaged as a Dockerfile + plugin-spec.yaml. Runs as an isolated CodeBuild action inside CodePipeline. Supports build_image (build at upload) or prebuilt (pre-built image.tar bundled in zip).
• Organization — the isolation boundary. All resources (pipelines, plugins, rules, quotas, secrets, billing) are scoped to an org with RBAC access control.
• Team — an organization optionally nested one level under a parent org (the org → team hierarchy). Opt-in: every org is a flat root by default. A team has its own members, quotas, and secrets, but its parent-org admins can manage it and visibility/quotas/compliance/analytics roll across the parent ↔ team relationship.
• Compliance Rule — Configurable constraint that validates plugins and pipelines before creation. Supports 18 operators, computed fields, and cross-field checks.
• Metadata Keys — Typed configuration keys controlling CodePipeline and CodeBuild behavior (IAM, networking, compute). See Metadata Keys.
• Secrets — Plugin credentials stored in AWS Secrets Manager under pipeline-builder/{orgId}/{secretName}. Injected at build time, never stored in images.

---

Guides

How-To

Document	Description
AWS Deployment	EC2 and Fargate deployment, post-deploy setup, drift detection
CDK Usage	PipelineBuilder construct, sources, stages, VPC, IAM, secrets
Compliance	Per-org rule engine with 18 operators, computed fields, audit trail
Audit Events	Cross-service audit event names + payload schemas (registry, etc.)
Environment Variables	Configuration reference for all services
Samples	Pipeline configs for 7 languages and CDK patterns

Reference

Document	Description
API Reference	REST endpoints for pipelines, plugins, compliance, reporting, AI
Metadata Keys	80 typed CodePipeline, CodeBuild, networking, and IAM configuration keys
Template Syntax	`` interpolation for pipeline configs and plugin specs
Plugin Catalog	125 pre-built plugins across 10 categories
Org → Team Hierarchy	Sub-organizations (teams) nested one level under a parent org — RBAC, visibility, quota, and compliance inheritance

---

Creating Pipelines

Dashboard and AI

The web UI at https://localhost:8443 provides visual pipeline and plugin management. The AI builder analyzes a Git repository (or a natural-language prompt) and generates the right stages and plugins automatically, streaming results over SSE. It works across five providers — Anthropic, OpenAI, Google, xAI, and Amazon Bedrock — and can fall back to a secondary provider if the primary one is unavailable.

Default credentials (created by init-platform.sh local on a fresh install):

Field	Value
Identifier	admin@internal
Password	SecurePassword123!

These defaults are only accepted on DEPLOY_TARGET=local. The minikube/ec2/fargate targets refuse the defaults and require the operator to type real values at the init-platform.sh prompt, so a production-style init won’t silently create an account with this password. Change the password from the dashboard immediately after first login on any environment that’s reachable beyond your laptop.

CLI

npm install -g @pipeline-builder/pipeline-manager
export PLATFORM_TOKEN=<jwt-from-login>

pipeline-manager upload-plugin --file ./node-build.zip --organization my-org --name node-build --version 1.0.0
pipeline-manager create-pipeline --file ./pipeline-props.json --project my-app --organization my-org
pipeline-manager deploy --id <pipeline-id> --profile production

REST API

# Create a pipeline
curl -X POST https://localhost:8443/api/pipelines \
  -H "Authorization: Bearer $TOKEN" -H "x-org-id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "organization": "my-org",
    "pipelineName": "my-app-pipeline",
    "accessModifier": "private",
    "props": {
      "project": "my-app",
      "organization": "my-org",
      "synth": {
        "source": { "type": "github", "options": { "repo": "my-org/my-app", "branch": "main" } },
        "plugin": { "name": "cdk-synth", "version": "1.0.0" }
      }
    }
  }'

# AI-generate a pipeline
curl -X POST https://localhost:8443/api/pipelines/generate \
  -H "Authorization: Bearer $TOKEN" -H "x-org-id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Build a Node.js app from GitHub, run tests, and deploy with CDK", "provider": "anthropic", "model": "claude-sonnet-4-20250514"}'

See the API Reference for the full endpoint list.

CDK Construct

import { App, Stack } from 'aws-cdk-lib';
import { PipelineBuilder } from '@mwashburn160/pipeline-core';

const app = new App();
const stack = new Stack(app, 'MyPipelineStack', {
  env: { account: '123456789012', region: 'us-east-1' },
});

new PipelineBuilder(stack, 'MyPipeline', {
  project: 'my-app',
  organization: 'my-org',
  synth: {
    source: {
      type: 'github',
      options: { repo: 'my-org/my-app', branch: 'main',
        connectionArn: 'arn:aws:codestar-connections:us-east-1:...:connection/...' },
    },
    plugin: { name: 'cdk-synth', version: '1.0.0' },
  },
  stages: [
    { stageName: 'Test', steps: [{ name: 'unit-tests', plugin: { name: 'jest', version: '1.0.0' } }] },
    { stageName: 'Deploy', steps: [{ name: 'deploy-prod', plugin: { name: 'cdk-deploy', version: '1.0.0' }, env: { ENVIRONMENT: 'production' } }] },
  ],
});

See Samples for more CDK patterns.

---

Start / Stop

Local (Docker Compose)

cd deploy/local && ./bin/startup.sh        # Start
cd deploy/local && docker compose down     # Stop
cd deploy/local && docker compose down -v  # Stop + remove volumes

Minikube

bash deploy/minikube/bin/startup.sh        # Start
bash deploy/minikube/bin/shutdown.sh       # Stop
kubectl get pods -n pipeline-builder       # Check

AWS EC2

sudo bash /opt/pipeline/pipeline-builder/deploy/aws/ec2/bin/startup.sh    # Start
sudo bash /opt/pipeline/pipeline-builder/deploy/aws/ec2/bin/shutdown.sh   # Stop
sudo -u minikube kubectl get pods -n pipeline-builder             # Check

AWS Fargate

cd deploy/aws/fargate
bash bin/deploy.sh --stack-prefix pb --region us-east-1 --domain app.example.com  # Deploy
bash bin/teardown.sh --stack-prefix pb --region us-east-1                          # Teardown

See AWS Deployment for full instructions and post-deploy setup.

Post-Deploy: Initialize Platform

After starting any target, run init-platform.sh to register the admin user and load plugins:

# Local / Minikube — interactive
./deploy/bin/init-platform.sh local
./deploy/bin/init-platform.sh minikube

# EC2 — requires minikube user context
sudo -u minikube PLATFORM_BASE_URL=https://your-ip bash /opt/pipeline/pipeline-builder/deploy/bin/init-platform.sh ec2

# Non-interactive with prebuilt images and controlled parallelism
PLUGIN_BUILD_STRATEGY=prebuilt PARALLEL_JOBS=2 ./deploy/bin/init-platform.sh local

Key env vars: PLUGIN_BUILD_STRATEGY (build_image/prebuilt), PLUGIN_CATEGORY (comma-separated filter), PARALLEL_JOBS (upload concurrency, auto-lowered to 1 for prebuilt), FORCE_REBUILD (rebuild existing image.tar files).

Admin credentials prompted by init-platform.sh:

Target	Identifier default	Password default	Defaults accepted?
local	admin@internal	SecurePassword123!	yes — hit Enter to accept
minikube / ec2 / fargate	none	none	no — operator must type real values

Set PLATFORM_IDENTIFIER and PLATFORM_PASSWORD env vars (or PLATFORM_TOKEN for an existing JWT) to skip the prompts in CI.

---

Organizations

Organizations are the isolation boundary — each one is a self-contained workspace. Every resource — pipelines, plugins, compliance rules, quotas, secrets, and billing — is scoped to an organization. Organizations can optionally nest teams (see Teams below). This section covers admin tasks; new evaluators can skip ahead to Architecture.

Creating an Organization

Register an account, then create one or more organizations. The creator becomes the owner.

From the dashboard — navigate to Team and click Create Organization.

From the API:

curl -X POST https://localhost:8443/api/organization \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"acme-platform","displayName":"Acme Platform Team"}'

Roles

Role	Capabilities
Owner	Full control — manage members, transfer ownership, delete org
Admin	Manage plugins, pipelines, compliance rules, quotas, and invite members
Member	Create and manage their own pipelines and plugins

Invite members via email from the dashboard or API. A user can belong to multiple organizations.

Teams (Org → Team Hierarchy)

A team is an organization nested one level under a parent (root) organization. Nesting is opt-in — every organization is a flat root until you create a team under it, and teams can’t have their own sub-teams (the hierarchy is one level deep). A team is a full organization: it has its own members, roles, quotas, secrets, and billing.

What the parent ↔ team relationship adds on top of plain organizations:

• Effective RBAC — a parent-org admin/owner can administer its teams (manage members, rules, quotas) without a separate membership; team-local roles still apply within the team.
• Inherited plugin visibility — a team sees its parent’s private plugins in addition to its own and the public catalog.
• Compliance propagation — a parent rule marked apply to child teams is enforced on its teams.
• Shared quota cap — a parent’s limit can be shared across the subtree (the root cap is checked before each team’s own atomic increment).
• Rolled-up analytics — a parent admin can include child-team data in execution reports.

A user can belong to several organizations and teams at once and acts within one at a time (switch with the org switcher).

Creating / managing teams — on the dashboard Members page, an admin of a root org uses Create Sub-Org / Team to nest a new team and Manage teams (per member) to add or remove a member across the org’s teams in one step. Via the API, POST /api/organization accepts a parentOrgId, and POST /api/organization/:id/members/bulk-add adds a user to several teams at once.

Feature Tiers

Feature	Developer	Pro	Unlimited
Pipeline / plugin CRUD	yes	yes	yes
AI pipeline generation	-	yes	yes
AI plugin generation	-	yes	yes
Bulk operations	-	yes	yes
Audit log	-	-	yes
Custom integrations	-	-	yes
Priority support	-	yes	yes

System org users always have access to all features.

What Each Org Controls

• Plugins — upload private plugins or use shared public ones; control which versions are available
• Compliance rules — enforce security standards, naming conventions, resource limits
• Quotas — set limits on pipelines, plugins, and API calls
• Billing — per-org subscription plans and usage tracking
• Secrets — stored in AWS Secrets Manager, injected at build time

---

Architecture

flowchart TB
    UI[Dashboard / CLI] --> NGINX[Nginx<br/>TLS + Routing]
    NGINX --> PIPE[Pipeline Service]
    NGINX --> PLUG[Plugin Service]
    NGINX --> PLAT[Platform Service]
    PIPE --> COMP[Compliance]
    PLUG --> REP[Reporting]
    PLAT --> QB[Quota / Billing]
    COMP & REP & QB --> DB[(PostgreSQL / MongoDB / Redis)]

Service	Purpose
Platform	Auth, orgs, users, JWT, RBAC
Pipeline	Pipeline CRUD, AI generation, CDK synthesis
Plugin	Plugin CRUD, Docker image builds, AI generation
Compliance	Per-org rule enforcement, policy management, audit trail
Reporting	Execution analytics via EventBridge ingestion
Quota	Resource limits per organization
Billing	Subscriptions and usage billing
Message	Org announcements and conversations

For end-to-end request → build → deploy flow diagrams, see Architecture Flow. For the case for adopting Pipeline Builder org-wide, see Organization Benefits.

---

Plugin Categories

125 plugins across 10 categories. See the Plugin Catalog for the full list.

Category	Count	Details
Language	11	Java, Python, Node.js, Go, Rust, .NET
Security	40	Snyk, SonarCloud, Trivy, Veracode, Semgrep
Quality	17	ESLint, Prettier, Checkstyle, Clippy, Ruff
Testing	14	Jest, Pytest, Cypress, Playwright, k6
Artifact	16	Docker, ECR, GHCR, npm, PyPI, Maven
Deploy	13	Terraform, CloudFormation, Kubernetes, Helm, CDK
Infrastructure	5	CDK synth, manual approval, S3 cache, shell
Monitoring	3	Datadog, New Relic, Sentry
Notification	5	Slack, Teams, PagerDuty, email
AI	1	Dockerfile generation (multi-provider)

---

Next Steps

• First time? Deploy Local and walk through Creating Pipelines.
• Setting up for your team? Read Organization Benefits, then Organizations above.
• Wiring CI from code? CDK Usage → Samples → Template Syntax.
• Going to production on AWS? AWS Deployment covers EC2, Fargate, drift detection, and event reporting.