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 EKS
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 EKS deployment, post-deploy setup, drift detection
Pipeline Manager (CLI)	pipeline-manager CLI — install the platform (provision), build/deploy pipelines, manage plugins, run audits
CDK Usage	PipelineBuilder construct, sources, stages, VPC, IAM, secrets
Compliance	Per-org rule engine with 18 operators, computed fields, audit trail
Roles & Permissions	Permission catalog, built-in Roles, requirePermission enforcement, session invalidation
Audit Events	Tamper-evident audit trail — hash-chain + /audit/verify, ingest security, durable spool, action catalog
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	119 pre-built plugins across 10 categories
Org → Team Hierarchy	Teams nested one level under a parent org — RBAC, visibility, quota, and compliance inheritance
Billing Add-on Bundles	Stackable add-ons that raise an account’s pooled caps (seats, pipelines, plugins, storage) and unlock features

---

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 docker on a fresh install):

Field	Value
Identifier	admin@internal
Password	SecurePassword123!

init-platform.sh is non-interactive: it reads PLATFORM_IDENTIFIER and PLATFORM_PASSWORD from the environment and falls back to the defaults above when unset — on every target. On any non-local or production target, export real PLATFORM_IDENTIFIER / PLATFORM_PASSWORD before running — otherwise the admin is created with this trivial dev password. Change the password from the dashboard immediately after first login on anything 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 '@pipeline-builder/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/docker && ./bin/setup.sh        # Start
cd deploy/local/docker && docker compose down     # Stop
cd deploy/local/docker && docker compose down -v  # Stop + remove volumes

Minikube

bash deploy/local/minikube/bin/setup.sh        # Start
bash deploy/local/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 EKS

cd deploy/aws/eks
bash bin/setup.sh --domain app.example.com --hosted-zone-id Z123 --region us-east-1     # Deploy
bash bin/shutdown.sh --cluster-name pipeline-builder --region us-east-1 --yes           # Teardown

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

Post-Deploy: Initialize Platform

init-platform.sh registers the admin user and loads plugins. The AWS deploys self-init by default (the provision default --init auto) — EC2 on first boot, EKS in setup.sh’s final phase (over a kubectl port-forward); on local/minikube provision runs it for you. You only run it by hand when you deployed with --init manual:

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

# EC2 (only if --init manual) — requires the minikube user context, on the box
sudo -u minikube PLATFORM_BASE_URL=https://your-ip bash /opt/pipeline/pipeline-builder/deploy/bin/init-platform.sh ec2

# EKS (only if --no-auto-init / --init manual) — run with kubectl access; it port-forwards to svc/nginx
env -u PLATFORM_BASE_URL ./deploy/bin/init-platform.sh eks

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

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).

Flags: --cleanup (remove plugin.zip/image.tar after upload), --continue-on-build-failure (proceed past per-plugin build failures), --force (rebuild the base images and the CodeBuild bootstrap image from scratch, ignoring the docker-cache / registry-tag skips — use after changing a base Dockerfile or the bootstrap image).

Admin credentials — init-platform.sh is non-interactive and reads them from the environment, falling back to defaults when unset:

Env var	Default (used if unset)
PLATFORM_IDENTIFIER	admin@internal
PLATFORM_PASSWORD	SecurePassword123!

The defaults apply on every target, so export real values on minikube/ec2/eks (or any shared/production environment) before running — otherwise the admin is created with the trivial dev password.

Fresh-install super-admin bootstrap. init-platform.sh registers the admin into the reserved system organization, and that org can only be created by an email listed in the platform’s BOOTSTRAP_SUPERADMIN_EMAILS (the controlled first-super-admin path). So on a fresh install, PLATFORM_IDENTIFIER must be listed in BOOTSTRAP_SUPERADMIN_EMAILS. The stock defaults align (both admin@internal); if you set a custom PLATFORM_IDENTIFIER, add it to BOOTSTRAP_SUPERADMIN_EMAILS and restart the platform before running init — otherwise the system registration is rejected (403) and no super-admin is bootstrapped.

---

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 — open the Organizations page and click Create Organization. (Teams — organizations nested under a parent — are created from the Members page with Create Team; see Teams.)

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.

Permissions

Access is granted through Roles — a Role is a named set of fine-grained resource:action permissions (e.g. pipelines:write, plugins:publish, members:manage, roles:manage, compliance:write, billing:manage, reports:rollup, org:settings). A user’s effective permissions are the union of the Roles assigned to them — there is no separate role-based baseline. Every org seeds built-in Roles (Admin, Member; the system org also gets Super Admin), and admins with roles:manage can add custom Roles (e.g. “Billing Manager”); Super Admins hold all. Endpoints enforce writes via requirePermission(...), and :read permissions are enforced too (withholding e.g. reports:read blocks that read). registry:read/write are Super-Admin-only and never grantable to a custom Role.

Full catalog, built-in bundles, enforcement, and session-invalidation: see Roles & Permissions.

Manage Roles from the dashboard, or via the API:

GET|POST    /api/organization/:id/roles                       # list / create Roles
PUT|DELETE  /api/organization/:id/roles/:roleId               # update / delete a Role
POST|DELETE /api/organization/:id/roles/:roleId/members/:uid  # add / remove a Role member

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 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	Team	Enterprise
Pipeline / plugin CRUD	yes	yes	yes	yes
AI pipeline generation	-	yes	yes	yes
AI plugin generation	-	yes	yes	yes
Bulk operations	-	yes	yes	yes
Audit log	-	-	yes	yes
Custom integrations	-	-	-	yes
Priority support	-	yes	yes	yes
Plugins	25	50	100	250
Pipelines	5	10	200	200
Seats (members)	1	1	10	25
Price / month	$0	$49	$149	$399

System org users always have access to all features. Base limits are raised by add-on bundles and are env-overridable (QUOTA_TIER_<TIER>_<LIMIT>, BILLING_PLAN_<TIER>_MONTHLY).

Add-on bundles — an account can stack purchasable add-ons on top of its tier to raise pooled caps (extra seats, pipelines, plugins, API/AI calls, storage) or unlock features (audit log, SSO). Effective limits = tier base + add-ons, shared across the account’s teams. See Billing Add-on Bundles.

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 — per-org limits on pipelines, plugins, API/AI calls, storage, and more (nine tracked resource types), plus member seats; a parent’s caps can be pooled across its teams
• Billing — per-account subscription tier (Developer / Pro / Team / Enterprise) plus stackable add-on bundles that raise pooled caps
• 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

119 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	34	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, EKS, drift detection, and event reporting.