Software Factories on AWS

Self-hosted platform for standing up and running software factories on AWS: complete DevSecOps environments with secure delivery pipelines, supply-chain controls, compliance evidence and multi-tenant governance — in minutes, not months.

Documentation

Setup, usage and reference for Pipeline Builder.

Highlights

Overview

Pipeline Builder is a self-hosted platform for deploying and running software factories on AWS: complete DevSecOps environments where secure delivery pipelines, supply-chain controls, compliance evidence and multi-tenant governance arrive together. Pipelines are assembled from reusable, containerized plugins and deploy as native AWS CodePipeline and CodeBuild in your own account.

This page is the documentation index. It links every setup, usage and reference guide, grouped by task.

How it works

The shortest accurate description of the whole system:

  1. You define a pipeline through the dashboard, an AI prompt, the CLI, the REST API or the CDK construct.
  2. Each step references a plugin — a container image with a declarative spec.
  3. Compliance validates it before anything is created, so policy is enforced at the gate.
  4. Synthesis turns the definition into CloudFormation via AWS CDK.
  5. It deploys as native CodePipeline + CodeBuild in your own AWS account.
  6. Execution events stream back for analytics, DORA metrics and reports.

Architecture Flow draws each of those steps in detail.

Configuration

The path from nothing to a working pipeline:

  1. Deploy the platform — Local or Minikube to evaluate, EC2 / EKS for real use. The recommended installer is infra provision.
  2. Onboard your organization — Onboarding walks the full flow: initial admin login, create org, invite members, create an access key, store the service tokens, set up event reporting, first pipeline.
  3. Set your guardrails — Compliance rules and Roles & Permissions.
  4. Build pipelines — dashboard, AI prompt, CLI, REST API or CDK; see Build below.
  5. Operate it — Deploy Operations, and wire a backup before you need one.

Start Here

The path from zero to a working pipeline:

  1. Deploy the platform — Local / Minikube for eval, or EC2 / EKS for real use. The recommended installer is infra provision.
  2. Onboard your organization — Onboarding a New Organization walks the full flow: initial admin login → create org → invite members → create an access key → store the service token → set up event reporting → first pipeline.
  3. Build pipelines — dashboard, AI prompt, CLI, REST API, or CDK (see Build below).
Guide For
Onboarding a New Organization First admin: login, org, members, access key, service-account keys (store-token), setup-events, first pipeline
AWS Deployment Deploy to EC2 / EKS — modes, post-deploy setup, reporting, teardown
Pipeline Manager (CLI) The pipeline-manager CLI — infra provision, build/deploy pipelines, audits
Deploy Operations Ops runbook — preflight, secrets rotation, backups, teardown
Secret Rotation Rotating every secret with zero downtime — JWT, refresh, at-rest key, alert relay, registry signing key
Access Keys and Machine Credentials Issuing personal access keys and provisioning the three stored machine credentials
Ecosystem Moderation For Ecosystem Managers: the publish-request queue, two-person approval, separation of duties, auto-approval rules, takedowns, re-sign jobs, the bootstrap exception

Key Concepts

Guides by task

Build

Author and ship pipelines and plugins.

Document Description
Developer Guide Five ways to create a pipeline + cut-and-paste plugin patterns for 7 languages
CDK Usage PipelineBuilder construct, sources, stages, VPC, IAM, secrets
Template Syntax `` synth-time interpolation for pipeline configs + plugin specs, and golden-path templates
Metadata Keys Typed CodePipeline / CodeBuild / networking / IAM configuration keys
Plugin Catalog 119 pre-built plugins across 10 categories, and how to author your own
Installing Plugins Trust tiers, installs and version policies, the per-org consumption policy, reviews and reporting
Publishing Plugins Publisher profiles, publish requests and moderation, catalog metadata, pausing a plugin
Developer Portal Catalog ownership & My Services, golden-path templates, per-pipeline maturity scorecards
Samples Ready-to-load pipeline templates for 7 languages + CDK patterns
Testing Conventions Shared mock factories, real authz gates in tests, coverage ratchets, the permission contract, and the traps that cost people a day

Govern

Organizations, access, policy, and billing.

Document Description
Organizations & Teams Isolation boundary, org creation, the org → team hierarchy
Roles & Permissions Permission catalog, built-in Roles, enforcement, session invalidation
Permission Contract The hand-maintained route-to-permission table — a diff here is a permission change and is reviewed as one
Compliance Per-org rule engine — 18 operators, computed fields, enforcement, audit trail
Authentication & SSO OAuth social login + per-org enterprise SSO (OIDC or SAML 2.0), just-in-time membership and SCIM 2.0 directory provisioning
Audit Events Tamper-evident hash-chained trail, /audit/verify, action catalog
Logs Per-organization application logs: search syntax, entry detail, raw view, download, masking
Billing Providers Setup walkthroughs for Stripe + AWS Marketplace (keys, webhooks, entitlements, metering)
Billing Add-on Bundles Stackable add-ons that raise pooled caps (seats, pipelines, plugins, storage)
Billing Discounts Coupon codes + usage credits — one-time/recurring/credit, grant or self-serve

Operate

Run, secure, and observe the platform.

Document Description
AWS Deployment EC2 / EKS deploy, post-deploy setup, reporting infra, drift detection
Deploy Operations Runbook — preflight, secrets rotation, backups & DR, teardown
Secret Rotation Per-secret rotation runbooks — overlap windows, restart order, verification, rollback, the lingering-rotation alert
Access Keys and Machine Credentials Issuing personal keys, provisioning the platform-automation / registry-push / reporting-ingest service accounts, what to watch
Service Mesh Istio ambient — STRICT mTLS + identity-based L4 authZ, plus per-internal-route L7 policies via a waypoint (local, EC2, EKS)
Environment Variables Every configuration variable, by subsystem
DORA Metrics Deploy frequency, change-failure rate, MTTR, measured lead time, build health (Enterprise / Advanced Reporting)
Stakeholder Reports Scheduled manager-facing reports — frozen period snapshots, review and publish, recipients, share links (Pro+ add-on)
Incident Webhook Point PagerDuty/Datadog/Alertmanager at the platform (native Alertmanager adapter, self-serve token, per-org window, admin UI) for automated post-deploy CFR + real MTTR
Notifications Email, Slack, webhooks and the in-app inbox — the operator switches (EMAIL_ENABLED, SES, SLACK_*, the alert relay) and the per-org settings that ride on them

Reference

Look things up.

Document Description
Content Index A–Z keyword/topic index — find where any subject is documented
API Reference REST endpoints for pipelines, plugins, compliance, reporting, AI
Template Syntax Full `` grammar, scopes, filters, error catalog
Metadata Keys The complete typed metadata-key reference
Error Handling Error-to-HTTP convention — throw typed AppErrors
Architecture Flow End-to-end flows: plugin build, pipeline create, synth, execution

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. The create dialogs default to Ask agent, which drafts the pipeline or plugin through the Ask assistant’s tools (with the chosen server-configured model) for you to review; pick a provider directly to call its generator instead.

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

Field Value
Identifier admin@internal
Password Pipeline-Builder-Dev-2026!

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
pipeline-manager auth login          # browser sign-in; stores the session locally
# (in CI instead: export PLATFORM_TOKEN=<access key from "auth pat">)

pipeline-manager plugin upload --file ./node-build.zip   # name + version come from plugin-spec.yaml
pipeline-manager pipeline create --file ./pipeline-props.json --project my-app --organization my-org
pipeline-manager pipeline 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",
    "visibility": "private",
    "props": {
      "project": "my-app",
      "organization": "my-org",
      "synth": {
        "source": { "type": "github", "options": { "repo": "my-org/my-app", "branch": "main" } },
        "plugin": { "name": "cdk-synth", "filter": { "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-5"}'

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/cdk';

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', filter: { version: '1.0.0' } },
  },
  stages: [
    { stageName: 'Test', steps: [{ name: 'unit-tests', plugin: { name: 'jest', filter: { version: '1.0.0' } } }] },
    { stageName: 'Deploy', steps: [{ name: 'deploy-prod', plugin: { name: 'cdk-deploy', filter: { 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 infra provision default --init auto) — EC2 on first boot, EKS in setup.sh’s final phase (over a kubectl port-forward); on local/minikube infra 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 BUILD_BOOTSTRAP=y LOAD_PLUGINS=y LOAD_COMPLIANCE=y LOAD_TEMPLATES=y 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 BUILD_BOOTSTRAP=y LOAD_PLUGINS=y LOAD_COMPLIANCE=y LOAD_TEMPLATES=y ./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

The LOAD_* gates are not optional on a non-interactive run. LOAD_PLUGINS, LOAD_TEMPLATES and LOAD_COMPLIANCE each default to n, and BUILD_BOOTSTRAP is skipped when there is no TTY. Without them init-platform.sh registers the admin user and the two service accounts and then exits having loaded nothing — no plugins, no templates, no compliance rules. On a TTY they prompt (Load plugins? [y/N]), and the default is still no. This is what setup.sh’s own auto-init passes, so a hand re-run must pass it too.

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 Pipeline-Builder-Dev-2026!
PLATFORM_TOTP_CODE unset — only needed when re-running init for an admin who has an authenticator app (see Authentication)

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

Built-in Role (seeded permission bundle) What its permissions cover
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

The coarse owner/admin/member label on a membership is for display and ownership transfer only — it grants nothing. Permissions come only from the Roles assigned to a user; see Permissions.

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:

A user can belong to several organizations and teams at once and acts within one at a time (switch with the org switcher). A parent-org admin can also open any of its teams from the switcher without being on the team — the session runs as admin there on the authority inherited from the parent, with no roster entry and no seat (see Authentication). A parent admin can delete one of its teams (restorable during the retention window from the parent’s recently-deleted list); a sysadmin can move a team to another eligible root, split it out as a standalone org, or bring a team-less root in as a team.

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. Team-only UI (the Teams list, Manage teams, the “Include child teams” rollup toggles on Reports and Executions, and the per-team usage and cost-by-team breakdowns on Billing) appears only once an org actually has a team. GET /api/user/organizations reports each membership’s childOrgCount for this purpose; Create Team itself is always shown on an eligible root org.

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
Advanced Reporting (DORA) add-on add-on add-on yes
Team Usage Analytics - add-on add-on yes
Custom integrations - - - yes
Priority support - yes yes yes
Plugins 25 50 75 150
Pipelines 2 5 6 30
Seats (members) 1 1 3 15
Price / month $0 $39 $79 $599

Unlimited — a fifth tier with every quota uncapped and all features on. It is the default tier when billing is disabled (BILLING_ENABLED=false), so a self-hosted install with no billing runs everything uncapped out of the box. When billing is enabled it is never shown, selectable, or purchasable — it is filtered out of the plans list and tier pickers.

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 (Advanced Reporting, Team Usage Analytics, curated compliance libraries — SSO is a Team-tier feature, not an add-on). Effective limits = tier base + add-ons, shared across the account’s teams. See Billing Add-on Bundles.

What Each Org Controls

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