Before Shipwright, your options were...

How We Got Here — The Evolution

Understanding why each tool exists helps you explain the landscape at the table:

One-sentence definition

Shipwright is a Kubernetes-native framework that provides a unified API for building container images, powered by Tekton, with pluggable build strategies.

The Key Insight

This separation is what makes everything else possible — tool flexibility, governance, simplicity, and security.

Four Pillars

The 30-Second Pitch

Key Analogies (pick one that fits)

Container Image Basics

• OCI Image Spec — container images are standardized. Any OCI-compliant tool produces the same format. This is why tool choice matters less than people think — the output is the same regardless of whether Buildah, Kaniko, or BuildKit built it.
• Layers — images are stacks of filesystem layers. Each Dockerfile instruction creates a layer. Understanding this helps explain caching: unchanged layers are reused.
• Image Digest — a SHA256 hash of the image manifest. Shipwright records this in BuildRun status for audit.
• Multi-arch / Manifest Lists — a single image tag can point to multiple architecture-specific images via an OCI Index (manifest list). Critical for ARM64 + AMD64 support.

CNCF Landscape Position

Shipwright sits between the developer and Tekton. It's not a CI/CD system — it's a build-specific abstraction layer.

Shipwright Project Structure

Architecture Overview

Override Precedence (the key design insight)

This is consistent across every overridable field: timeout, paramValues, output, env, stepResources, nodeSelector, tolerations, schedulerName, runtimeClassName, volumes. Platform teams set sensible defaults; developers override per-run.

Minimal Build (12 lines)

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: my-app
spec:
  source:
    type: Git
    git:
      url: https://github.com/shipwright-io/sample-go
    contextDir: docker-build
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  output:
    image: quay.io/my-org/my-app:latest
    pushSecret: my-registry-creds

That's it. Source, strategy, output. The developer doesn't need to know Tekton, pipelines, or Buildah flags.

Full Spec Fields

output:
  image: registry.example.com/app:latest
  pushSecret: creds
  vulnerabilityScan:
    enabled: true
    failOnFinding: true
    ignore:
      issues: [CVE-2022-12345]
      severity: Low
      unfixed: true

paramValues:
- name: build-args
  values:
  - configMapValue:
      name: project-config
      key: node-version
      format: NODE_VERSION=${CONFIGMAP_VALUE}
  - value: DEBUG_MODE=true
  - secretValue:
      name: npm-registry
      key: auth-token
      format: NPM_AUTH_TOKEN=${SECRET_VALUE}

Controller Flow

Two Patterns

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: my-app-run-1
spec:
  build:
    name: my-app        # references existing Build
  serviceAccount: pipeline
  timeout: 15m          # override Build's timeout

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: standalone-run
spec:
  build:
    spec:               # embed Build spec inline
      source:
        type: Git
        git:
          url: https://github.com/shipwright-io/sample-go
        contextDir: source-build
      strategy:
        kind: ClusterBuildStrategy
        name: buildpacks-v3
      output:
        image: quay.io/my-org/app:latest

What's in BuildRun Status (Audit Gold)

• Image digest — SHA256 of the built image
• Image size — compressed size
• Git commit SHA — exact commit that was built
• Git commit author — who committed
• Vulnerability scan results — CVE IDs with severities
• Build spec snapshot — copy of the Build spec at execution time (if the Build changes later, you still know what config produced each image)
• 30+ failure reason codes — rich error reporting: BuildRunTimeout, StepOutOfMemory, GitAuthInvalidKey, GitRevisionNotFound, etc.

Why Multiple Strategies?

There is no single "best" way to build a container image. Different teams have different needs:

Supported Strategies

How Do They Differ?

Quick decision guide — pick based on your constraints:

System Parameters (injected by controller)

The Push Model Decision

Strategy authors choose who pushes the image:

Comparison

Your Lines

Migration Path

• S2I builds: Shipwright has an S2I strategy — existing builder images still work
• Docker builds: Switch to the Buildah strategy (rootless, more secure)
• Jenkins Pipeline: Already deprecated — move to Tekton pipelines or Shipwright
• YAML conversion: Build YAML is simpler than BuildConfig — concepts map 1:1
• Tooling: Crane-based migration tool auto-converts BuildConfig → Build (dev preview)

Tool-Specific Details

Landscape Map

Why In-Cluster Builds Matter

For skeptics who say "just use GitHub Actions":

• Data sovereignty — source code and images never leave your cluster
• Air-gapped environments — works without internet access
• Unified RBAC — one access control system for everything
• Supply chain security — Tekton Chains provides SLSA attestations
• Cost predictability — no per-minute billing at scale
• Cloud portability — same build definitions work anywhere

Project Facts

Lines for the Table

Demo 1: Build Strategies (2-3 min)

Point: Same app, two different strategies, one-line change.

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: s2i-nodejs
spec:
  source:
    type: Git
    git:
      url: https://github.com/sclorg/nodejs-ex
  strategy:
    name: source-to-image
    kind: ClusterBuildStrategy
  paramValues:
  - name: builder-image
    value: image-registry.openshift-image-registry.svc:5000/openshift/nodejs:16-ubi9
  output:
    image: image-registry.openshift-image-registry.svc:5000/demo-builds/nodejs-ex:s2i

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-nodejs
spec:
  source:
    type: Git
    git:
      url: https://github.com/shipwright-io/sample-nodejs.git
    contextDir: docker-build
  strategy:
    name: buildah                    # <-- only this changes
    kind: ClusterBuildStrategy
  output:
    image: image-registry.openshift-image-registry.svc:5000/demo-builds/nodejs-ex:buildah

oc new-project demo-builds
oc create imagestream nodejs-ex
oc apply -f 01-s2i-nodejs-build.yaml
shp build run s2i-nodejs --follow
# Then switch strategy:
oc apply -f 02-buildah-nodejs-build.yaml
shp build run buildah-nodejs --follow

Demo 2: Build Volumes / Caching (3-5 min)

Point: Platform team sets up caching, developers get fast builds.

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-nodejs-cache
spec:
  source:
    type: Git
    git:
      url: https://github.com/shipwright-io/sample-nodejs.git
    contextDir: docker-build
  strategy:
    name: buildah-cache
    kind: BuildStrategy
  output:
    image: image-registry.openshift-image-registry.svc:5000/demo-builds/nodejs-ex:buildah
  volumes:
  - name: build-cache
    persistentVolumeClaim:
      claimName: build-cache          # PVC for layer caching

oc apply -f 00-cache-pvc.yaml           # Create the PVC
oc apply -f 01-buildah-cache-strategy.yaml  # Namespace strategy with cache volume
oc apply -f 02-buildah-nodejs-cache-build.yaml

time shp build run buildah-nodejs-cache --follow  # First: ~2 min
time shp build run buildah-nodejs-cache --follow  # Second: ~30 sec!

Demo Prep Checklist

The Basics

The OpenShift Crowd

The Platform Engineer

The Technical Deep-Dive

The Skeptic