# Add a Staging Overlay with Kustomize from a Linear Issue

Yes. An agent picks up the Linear issue, adds a Kustomize staging overlay for guestbook plus an Argo CD Application, validates it and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-staging-overlay/kustomize/), in a Project that has your repository.

## What the agent does

The agent starts from the Linear issue and the repository in its own sandbox, and inventories the Kustomize guestbook layout. In a tree like argoproj/argocd-example-apps, `kustomize-guestbook/kustomization.yaml` is a base with `namePrefix: kustomize-`, resources `guestbook-ui-deployment.yaml` and `guestbook-ui-svc.yaml`, and the Deployment already sets `replicas: 1` for `gcr.io/google-samples/gb-frontend:v5`. There is no `overlays/staging` (or similar) under that app, and the repo has no kubeconform or kustomize CI checks.

It adds a staging overlay that references the guestbook base, sets `namespace: staging` (or the name the issue prefers), a name suffix such as `-staging`, keeps one replica, and any staging-specific labels. It also adds an Argo CD `Application` manifest that points `spec.source.path` at that overlay directory so Argo can sync staging from the same repo. It does not rewrite unrelated Helm or Jsonnet examples.

For proof, it runs `kustomize build` on the base and on the staging overlay, then `kubeconform` (or `kubectl apply --dry-run=server` when a cluster is unavailable) on the rendered YAML for each app it touched. It adds a small script or Makefile target only if the repo has nowhere to hang those commands, preferring a documented command in the PR when the tree is examples-only.

Last, it opens a pull request that links the Linear issue, shows the overlay file tree and the Application YAML, and pastes the `kustomize build` / kubeconform exit status from the transcript.

## Start it with one API call

`POST https://api.prix.dev/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A Linear issue labeled agent says: \"Add a Staging Overlay with Kustomize. Add a staging overlay for kustomize-guestbook with one replica, a staging namespace and a name suffix, and an Argo CD Application that points at it.\" Do the work in this repository, add tests for it, run kustomize build and kubeconform for each app, and open a pull request that links back to the issue.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.prix.dev/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch. The description shows the new overlay path, namespace and name suffix, the Application's `source.path` and that `kustomize build` plus kubeconform were run on the rendered manifests. The Linear issue is linked.

The transcript keeps the build and validation commands with their output. Invalid overlays fail closed in the session instead of landing as silent YAML.

Before merging, a reviewer checks the Application's destination cluster/namespace fields, that the overlay does not accidentally patch production paths and that namePrefix from the base still composes cleanly with the staging suffix.

## Run it on every Linear issue labelled agent

In the console, an automation with a `linear` trigger on `linear.issue.labeled` and the label `agent` starts one run per labelled issue, with the issue as its context, in the Project's repository. Changes made by an app integration never fire it, so the agent's own updates do not start new runs.

From your own server, the same run is one `POST /o/{org}/sessions` per issue: put the repository in `resources`, and add the issue's `https://linear.app/<workspace>/issue/<ID>` URL there too to have Rush read it through your Linear connection into the prompt. A webhook on the API key posts `run.completed` or `run.failed` when the turn finishes, with the `session_url` to read the result.

## Why run it on Rush?

Kustomize overlays are easy to get wrong with conflicting namePrefix and nameSuffix. In a Rush sandbox the agent installs kustomize and kubeconform, renders the YAML and keeps the bytes in the transcript so reviewers see the exact staging objects without syncing Argo against a live cluster first.

A Linear label becomes a GitOps-ready PR on its own branch. Several overlay requests can render in parallel sandboxes, each bounded by the key's `max_concurrent` limit.

## Frequently asked questions

### Does it change the existing kustomize-guestbook base?

Only if the overlay cannot reference it cleanly. The preferred change is a new overlay directory that points at the base, leaving the original example intact for tutorials.

### Where does the Argo CD Application live?

Beside the overlay or under an `apps/` path consistent with the repo. The PR states the path and the `spec.source.path` value Argo should sync.

### What if kubeconform is not installed?

The agent installs it in the sandbox (or uses an equivalent dry-run validator), runs it and records the command in the PR so CI can adopt the same check later.

### Will it sync to my cluster?

No. It only adds manifests and validates them. Applying or syncing stays with Argo CD or your operator once the Application is registered.