DEV Community: Artur Havrylov

Per-PR Preview Environments with FluxCD

Artur Havrylov — Fri, 29 May 2026 00:24:59 +0000

You want a preview environment for every pull request - open a PR, get a working URL. On Kubernetes with Flux, there's no built-in way to get one: Kustomization and HelmRelease don't template themselves per PR.

The usual workarounds each have a catch:

a kubectl apply CI job - breaks GitOps, since the cluster drifts from git
Argo CD ApplicationSet - now you're running two GitOps controllers
a custom controller that watches your PRs - works, but it's yours to maintain

There's a lighter option: the Flux Operator's ResourceSet and ResourceSetInputProvider CRDs. Two YAML files per service, no custom code, no second control plane. This post is the full setup - copy-paste-able - using a backend service called api as the example.

What you'll build

A preview environment for every open PR, on its own URL (api-1234.preview.example.com).
Deploy gated on the image build - no ImagePullBackOff while CI is still running.
Automatic teardown when the PR closes - no cleanup job.
All in plain YAML, reconciled by Flux.

How it works

Three pieces make it work:

A watcher lists the PRs that are ready to deploy - it keys off a label your CI adds once the image is built.
A templater stamps out a full copy of your app for each PR: its own name, URL, and image tag.
Flux deploys those copies and keeps the cluster in sync as PRs open and close.

PR opened + labeled "build/image-ready"
        |
        v
Watcher  (ResourceSetInputProvider, polls every 5m)
  lists each open PR as { id, sha }
        |
        v
Templater  (ResourceSet)
  stamps out one environment per PR
        |
        v
Deployed preview env  (api-1234.preview.example.com)
  auto-deleted when the PR closes

The rest of this post is just wiring those three pieces in YAML.

Prerequisites

A cluster already running Flux (flux-system GitRepository + controllers).
The Flux Operator installed on top - it's a separate project from Flux core:

  helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \
    --namespace flux-system

Provider auth: a PAT (code-read scope) via secretRef - seal it so it lives in git - or workload identity (serviceAccountName + cloud IAM) to avoid storing a token.

The two CRDs

The watcher and templater are two CRDs from the Flux Operator:

ResourceSetInputProvider - the watcher. Polls a source (Azure DevOps, GitHub, GitLab) on an interval and emits one input per open PR, each with fields like inputs.id (PR number) and inputs.sha (head commit).
ResourceSet - the templater. Takes those inputs and renders a set of Kubernetes resources once per input, via << inputs.id >> substitution.

Because the watcher and the template are separate, you can swap an Azure DevOps source for a GitHub one without touching what gets deployed.

Step 1: Watch PRs

The input provider for the api service - one repo, polled every five minutes:

apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSetInputProvider
metadata:
  name: api-prs
  namespace: app-dev
  annotations:
    fluxcd.controlplane.io/reconcileEvery: "5m"
spec:
  type: AzureDevOpsPullRequest
  url: https://dev.azure.com/{org}/{project}/_git/api
  secretRef:
    name: azure-devops-auth
  skip:
    labels:
      - "!build/image-ready"

type: AzureDevOpsPullRequest queries active PRs. GitHubPullRequest / GitLabMergeRequest work the same way, so nothing else in the setup changes.
skip.labels: ["!build/image-ready"] is the key line. The leading ! inverts the match: skip any PR that does NOT have build/image-ready. Net effect - only labeled PRs become inputs.
That label is the deploy-gates-on-build trick. Your CI sets build/image-ready only after it has built and pushed the image. Until then the provider doesn't see the PR, so the deploy can't race the build. No webhooks, no retry loops, no ImagePullBackOff.

Step 2: Template the Kustomization

The ResourceSet consumes those inputs and renders one Kustomization per PR:

apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
metadata:
  name: api-pr-envs
  namespace: app-dev
spec:
  inputsFrom:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSetInputProvider
      name: api-prs
  resources:
    - apiVersion: kustomize.toolkit.fluxcd.io/v1
      kind: Kustomization
      metadata:
        name: api-pr-<< inputs.id >>
        namespace: app-dev
      spec:
        dependsOn:
          - name: app-common-dev      # shared namespace, ingress class, configmaps
            namespace: flux-system
        interval: 10m
        retryInterval: 1m
        prune: true                   # cascade-delete on teardown
        wait: false
        sourceRef:
          kind: GitRepository
          name: flux-system
          namespace: flux-system
        path: ./clusters/eks/apps/api/pr-template
        postBuild:
          substitute:
            PR_NUMBER: << inputs.id | quote >>
            COMMIT_SHA: "<< inputs.sha >>"

If 7 PRs are open, this renders 7 Kustomization objects: api-pr-1234, api-pr-1289, and so on - each one you can inspect, retry, or delete on its own. postBuild.substitute passes PR_NUMBER and COMMIT_SHA down into the manifests at the templated path. dependsOn makes each per-PR env wait for shared infra so they don't race during cluster bootstrap.

Step 3: The per-PR overlay

This is the piece most write-ups skip. The path above points at a Kustomize overlay that turns one base manifest set into a PR-scoped copy:

# ./clusters/eks/apps/api/pr-template/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: app-dev

resources:
  - ../../../../base/api          # the normal, un-PR'd manifests

nameSuffix: -${PR_NUMBER}         # api -> api-1234, on EVERY resource
commonLabels:
  pr-env: "pr-${PR_NUMBER}"       # one label to find/watch the whole env

images:
  - name: registry.example.com/api
    newTag: pr-${PR_NUMBER}       # pull the image CI built for this PR

replicas:
  - name: api-deployment
    count: 1                      # previews don't need HA

patches:
  - path: pr-ingress-patch.yaml
  - path: pr-env-vars-patch.yaml
  # cluster-scoped resources can't be duplicated per PR - strip them
  - target: { kind: ClusterRole }
    patch: |
      $patch: delete
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata: { name: unused }
  - target: { kind: ClusterRoleBinding }
    patch: |
      $patch: delete
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata: { name: unused }

The mechanics that make this work:

nameSuffix: -${PR_NUMBER} is the isolation engine. Kustomize appends it to every resource name, so api becomes api-1234 across Deployment, Service, Ingress - no per-resource editing. Everything lives in one shared namespace; the suffix keeps PRs from colliding. (Simpler than namespace-per-PR, and you don't pay namespace setup cost on every env.)
images.newTag sets the image tag the Kustomize way instead of string-replacing inside the manifest - cleaner, and Kustomize validates it.
$patch: delete on cluster-scoped kinds is the gotcha nobody warns you about: ClusterRole/ClusterRoleBinding/ServiceAccount are cluster-scoped, so a name suffix would either collide or leak. Strip them from the overlay and provision them once in shared infra instead.

The two patches are small. Ingress gives the PR its own hostname:

# pr-ingress-patch.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
spec:
  rules:
    - host: api-${PR_NUMBER}.preview.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api
                port: { number: 80 }
  tls:
    - hosts: [api-${PR_NUMBER}.preview.example.com]

And the env patch stamps the commit SHA as a pod annotation:

# pr-env-vars-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  template:
    metadata:
      annotations:
        app/commit-sha: "${COMMIT_SHA}"   # changes on each push -> forces rollout
    spec:
      containers:
        - name: api
          env:
            - name: PUBLIC_URL
              value: "https://api-${PR_NUMBER}.preview.example.com"

Why bother? When you push a new commit to the same PR, the image tag stays the same (pr-1234), so the pod spec wouldn't change and Kubernetes wouldn't redeploy. Stamping the new COMMIT_SHA into an annotation forces a fresh rollout on every push.

Step 4: Cleanup is automatic

There's no teardown job. When PR #1234 closes (or loses its build/image-ready label):

On the next 5-minute poll, the input provider stops emitting an input for #1234.
The ResourceSet sees api-pr-1234 no longer maps to a live input and deletes that Kustomization.
Because that Kustomization has prune: true, it cascade-deletes everything it owns - Deployment, Service, Ingress, ConfigMap - all gone.

The whole environment unwinds within one reconcile cycle. "What should exist" is derived from "what PRs are open," and Flux drives the cluster toward it.

Gotchas worth knowing

Gate the deploy on the build. The !build/image-ready skip rule is doing real work - without it, Flux tries to deploy before CI pushes the image. Set the label as the last CI step.
Strip cluster-scoped resources ($patch: delete). They can't be safely suffixed per PR; share them from common infra.
Force rollouts with a SHA annotation if your image tag is stable per PR.
Poll latency is your iteration loop. 5m is a reasonable default - push, wait for CI, get a deploy. Shorter means more API calls to your provider.
dependsOn shared infra, or every preview env races namespace/ingress setup on bootstrap.
If you use a PAT: code-read scope is enough; keep it sealed.

Wrap-up

The same shape - watch a dynamic source, render a templated resource per item, reconcile both directions - shows up in Argo ApplicationSet, Crossplane Composition, and Terraform for_each. What the Flux Operator does well is keep it to two CRDs and pure YAML. If you're already on Flux, the cost is one Helm install plus a provider, a ResourceSet, and a small overlay per service - cheap enough that per-PR previews stop being a "someday" item.

The 80/20 Library-First Monorepo: Why Your Apps Should Be Almost Empty

Artur Havrylov — Sun, 03 May 2026 19:46:06 +0000

Most monorepos pay lip service to "share code via libraries." In practice, apps grow huge and libraries stay shallow. The shared/ folder becomes a junk drawer. New code goes wherever's easiest, which is usually wherever the developer is already typing - the app.

After scaling our frontend monorepo to 19 applications and 86 libraries (roughly 74,000 lines of TypeScript), I've seen this pattern from both sides: as the architect setting it up, and as the engineer who later inherits it. The takeaway: if your monorepo's library-first principle is just a guideline, it will erode. Mechanical enforcement is the only thing that scales.

Here's how we made library-first an architectural rule that's hard to violate.

Why "Just Put It in a Library" Fails

The default state of any monorepo: convention says "extract reusable code into libraries"; reality says "I'll do it later." Apps grow into hundreds of files because there's zero friction adding code there. Libraries stay thin because extraction is always an explicit decision someone has to make.

This isn't a discipline problem. It's a friction problem.

Three failure modes I keep seeing:

Apps as code containers. A junior dev needs a button component. They write it in apps/foo/src/components/Button.tsx. Two months later, three other apps have their own slightly different button. None know the others exist.

Shared as junk drawer. Senior devs do extract code, but libs/shared/ becomes a flat dumping ground with no internal structure. Finding a util becomes a 5-minute grep through libs/shared/.

Type confusion. "What kind of library is this?" "It's a library." UI components, business logic, API clients, and state stores all mixed together because the monorepo doesn't have language to distinguish them.

Tools like Nx provide module boundaries you can enforce. Unless they're enforced automatically, they aren't enforced.

The 80/20 Inversion

Our principle: applications are deployment containers, not code containers. They wire libraries together and configure routing. That's it.

How thin is "thin"? Look at one of our domain apps:

5 source files in the app
143 source files in the domain's libraries
That's 97% library code, 3% app code. We don't just hit 80/20, we exceed it.

The app folder has roughly four files: main.tsx (bootstrap), app.tsx (layout shell), routes.tsx (route config), and styles.scss. Here's how they wire together.

main.tsx mounts the router and wraps it with cross-cutting providers. Note where these providers come from: shared-ui and third-party packages, not domain-state. State libraries hold stores; cross-cutting concerns belong in shared.

// src/main.tsx
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ErrorBoundary } from '@scope/shared-ui';
import { routes } from './app/routes';

const queryClient = new QueryClient();
const router = createBrowserRouter(routes);

root.render(
  <ErrorBoundary>
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  </ErrorBoundary>,
);

The real wiring happens in routes.tsx - this is where features (each a separate library) connect to URL paths, lazy-loaded so each feature ships as its own bundle:

// src/app/routes.tsx
import { lazy } from 'react';
import type { RouteObject } from 'react-router-dom';
import { App } from '../app';

const DashboardPage = lazy(() =>
  import('@scope/domain-features-dashboard')
    .then(m => ({ default: m.DashboardPage })),
);

const SearchPage = lazy(() =>
  import('@scope/domain-features-search')
    .then(m => ({ default: m.SearchPage })),
);

export const routes: RouteObject[] = [
  {
    path: '/',
    element: <App />,
    children: [
      { index: true, element: <DashboardPage /> },
      { path: 'search', element: <SearchPage /> },
    ],
  },
];

That's the pattern: app boots, mounts routes, routes import features by name, features arrive as their own library. Adding a feature is a one-line addition to the routes file plus a new lib. Apps shrink to their essence; libraries hold everything that matters.

When code lives in libraries, it's testable in isolation, code-splittable per feature, reusable across apps, and promotable to shared without restructuring. When it lives inside the app, none of those properties hold. That's why we keep apps almost empty - in this structure, those properties are the default rather than something we have to engineer.

Type-Tagged Boundaries

Reusable libraries aren't enough on their own. You also need a vocabulary for what kind of library something is, plus rules about which kinds can depend on which.

We use 7 types, each with explicit dependency constraints:

Source type	Can depend on
`type:app`	feature, ui, data-access, state, util, hooks
`type:feature`	feature, ui, data-access, state, util, hooks
`type:state`	state, data-access, util
`type:ui`	ui, util
`type:data-access`	data-access, util
`type:hooks`	hooks, data-access, util
`type:util`	util

Read top-to-bottom: type:util is the foundation - pure functions, no deps. type:ui adds presentation - components built from utils, no business logic. type:data-access and type:state handle the data layer. type:feature orchestrates everything into pages and flows. type:app consumes features.

The rules are encoded in ESLint via @nx/enforce-module-boundaries. A type:ui library that imports from type:state fails lint. Not a warning - an error that blocks merge.

Why this matters: most monorepos treat "shared code" as a single category. We split it into seven, each with a contract about what it can know and depend on. Small change, outsized effect: a type:ui library is guaranteed to be presentation-only, because the toolchain prevents anything else.

Normalization Across Domains and Shared

Every domain follows the same 6-library template:

libs/{domain}/
├── data-access/    # API clients, types, services
├── state/          # State stores
├── ui/             # Domain-specific components
├── util/           # Constants, helpers
├── hooks/          # Custom hooks
└── features/       # Pages and flows

This uniformity matters more than it sounds. New developer joining a domain? They already know the layout from the previous one. Cross-team handoff? No mental retooling. Promoting someone to a new team? They're productive on day one.

But the bigger insight - the one that took me longest to appreciate - is that libs/shared/ follows the exact same structure:

libs/shared/
├── data-access/
├── ui/
├── util/
├── hooks/
└── features/

Same types. Same boundary rules. Same package conventions. Just consumed across all domains instead of one.

This solves a chronic monorepo problem: the promotion path from domain to shared.

In most setups, "this should be reusable" triggers a structural refactor: invent a new layout for shared/, rename packages, update imports, fight the boundary checker. Devs put it off, and shared/ either stays empty or becomes the junk drawer.

When shared/ mirrors domain structure, the structural problem is already solved. What varies is how much contract generalization each type needs:

Leaf types (util, ui, hooks): Often a git mv. Pure functions, presentation components, and most hooks promote nearly mechanically.
data-access: Needs generalization. Domain endpoints and types must become generic interfaces. Real work, but the structure is solved.
state and features: Hardest. They depend on multiple other types, and feature units often carry domain assumptions. Promoting a feature to shared is significant work - but the organizational problem is still solved.

The promotion friction goes from "refactor structure + generalize API" to just "generalize API." Roughly half the work, removed by symmetry alone.

Mechanical Enforcement (5 Layers)

Architecture as a guideline fails. Architecture as 5 reinforcing automated checks survives.

Layer 1: The Generator. New domains aren't hand-built. We run one command:

nx g @workspace/domain-app:create --name=my-domain

This scaffolds the app + 6 libraries, correctly tagged from birth. No after-the-fact tagging where someone forgets type:ui and the rule never matches. Tagging happens at scaffold time, by code, on every domain. This is the most important layer because it makes "incorrectly structured library" nearly unreachable.

Layer 2: ESLint module boundaries. Catches dependency violations at lint time. CI runs nx affected -t lint on every PR.

Layer 3: Lint-staged pre-commit. Runs eslint --fix on staged files. Quick errors get auto-fixed; structural errors block commit.

Layer 4: Husky pre-push. Before code leaves the developer's machine: knip:affected (unused imports), typecheck, lint:affected:fix. Slower checks that catch what pre-commit missed.

Layer 5: CI gates. Final wall: build, test, lint, typecheck on all affected projects. PRs can't merge if any layer below let something through.

A single layer fails because devs can disable rules locally, skip hooks with --no-verify, or just push without running tests. Five layers reinforcing the same architecture mean violations would have to slip past every checkpoint - including the generator that won't produce non-conformant code in the first place.

Honest Tradeoffs

This pattern isn't free.

Adoption friction. A new contributor walks into 6+ libraries per domain. There's a learning curve while the structure clicks - usually a few days. After that, the layout is identical across domains, and the consistency pays for itself.

Generator maintenance. Custom generators are code that needs upkeep. When Nx upgrades, when conventions change, when a new lib type emerges - the generator changes too. Plan for someone to own this.

Doesn't fit small projects. A single-app monorepo doesn't benefit from 6 libraries per domain - it's just complexity. Break-even is somewhere around 3+ apps with shared concerns. Below that, fewer libraries with looser boundaries is the right call.

The General Principle

The Nx-specific details are tactical. The principle is portable to any monorepo (Turborepo, Bazel, Yarn workspaces, Rush): structure should be enforced mechanically, not socially.

If you rely on developers to "remember to put it in the right library" or "remember to tag it correctly," you've already lost. The friction accumulates. Apps grow. shared/ becomes the junk drawer.

Make the right thing easy and the wrong thing hard. Then your architecture is real.