Preview environments for a microservice architecture with 10+ repositories.

One pull request shows one part

Record the complete set of service versions for every preview.

In a monorepo, one commit can identify the whole application. Across many repositories, each service has its own history. A branch may exist in only some repositories and may point to unrelated work in others.

We use a version map for the preview. The changed service uses its pull-request commit. Every other service keeps the exact version from a known-good staging or release baseline. This makes the preview repeatable and shows reviewers what is running.

Use the smallest stack that answers the review

Support quick service reviews and coordinated changes through one workflow.

Most changes affect one service. Build the candidate version for that service and combine it with baseline versions for the rest of the stack. This path keeps setup fast.

Changes across APIs, workers, identity or shared contracts need a coordination pull request that lists the exact commits taking part. After that, both paths use the same environment definition, naming, GitOps deployment, status and cleanup.

One small file

Keep the environment definition in a separate GitOps or automation repository.

We have found that a separate repository makes ownership clearer. Service workflows publish images. The automation repository records the combination that reviewers asked for. Argo CD reads that reviewed state.

Many repositories, one control path

Let service repositories build their images and let GitOps deploy the set.

Each service workflow builds and reports its own fixed image. The automation workflow adds those image references to the environment definition. Argo CD reads the definition, creates the applications and reports their health.

Narrow access and clear limits

Limit where ApplicationSets can read from and deploy.

ApplicationSets can create applications from Git files, pull requests or a combination of inputs. Keep those inputs in approved repositories and use an AppProject that lists the allowed repositories, clusters, namespaces and resource types.

Some resources must be ready before others. Use sync waves or clear dependencies so secrets, databases and migrations are healthy before workloads start. Test database and cloud-resource deletion separately, since Kubernetes cleanup can leave them behind.

• Keep ApplicationSet creation and project templates under platform-team control.
• Use credentials for each repository instead of one token with write access to every service.
• Limit preview destinations to a known namespace pattern and approved clusters.
• Use fixed, trusted versions of charts, shared workflows and images.
• Decide how databases, buckets and external resources will be deleted.

Copy only what the review needs

Choose which dependencies are separate for each preview.

A ten-service stack may also use identity, PostgreSQL, cache, messaging, object storage and external services. Copying every managed service for every pull request quickly becomes slow and expensive.

We usually separate a database schema, bucket or queue when state or migrations are part of the review. Stable identity and external test services can remain shared when reviewers can see that limit.

One result across many builds

Combine build, deployment and test results into one preview status.

A successful service build tells us that one image exists. The reviewer needs to know whether every required build finished, GitOps applied the changes, dependencies are healthy, migrations passed and the full test completed. Show partial failures instead of returning a URL that only partly works.

Use one preview ID in logs, metrics, DNS, namespace labels, GitOps applications and pull-request comments. The same ID lets cleanup find every part of the environment.

• Report the exact service versions that are running alongside Argo CD health.
• Stop older candidate builds when one of the participating branches changes.
• Set a limit on active stacks, namespace quotas and workload defaults.
• Remove inactive environment definitions even when one source pull request remains open.
• Check that cleanup removes external DNS, data branches, secrets and cloud resources as well as Kubernetes objects.

Add coordination after cleanup works

Start with one changed service against a known baseline.

Prove the single-service path first: build one candidate, use baseline versions for every other service, create the namespace, return the results and delete everything.

We have seen teams add multi-service coordination too early and spend time debugging version-map logic before cleanup is reliable. Add the coordination repository when a real cross-service change needs it.