What the agent does
The agent reads how the repository is reconciled before it decides where a secret can live. In a GitOps repository like fluxcd/flux2-kustomize-helm-example, clusters/staging/ and clusters/production/ each hold an ArtifactGenerator in artifacts.yaml that copies apps/base/**, the cluster's apps/<cluster>/** and infrastructure/** into two ExternalArtifact sources, and three Flux Kustomization objects: infra-controllers and infra-configs in infrastructure.yaml, and apps in apps.yaml, which has dependsOn: infra-configs, path: ./staging or ./production, prune: true and wait: true. None of them has a decryption block. apps/base/podinfo/release.yaml is a HelmRelease for the podinfo chart with inline values, and apps/staging/podinfo-values.yaml patches the chart version and hostname. Two files show the repository was built with encrypted secrets in mind: .fluxschema.yml already lists Secret:/sops under skipJSONPath, and scripts/validate.sh passes --skip-json-path=/sops by default, so a SOPS-encrypted Secret validates without complaint. The e2e.yaml workflow installs Flux on a kind cluster, points a GitRepository at the branch being pushed and waits for apps and helmrelease/podinfo to be ready, so any secret added under apps/staging must be decryptable in CI or the workflow fails.
The agent adds a .sops.yaml at the repository root with one creation rule: a path_regex covering apps/ and infrastructure/, encrypted_regex: ^(data|stringData)$ so a Secret's metadata and type stay readable in review and only the values are ciphertext, and an age list with the staging key, the production key and a third key for CI, all public keys taken from the prompt. One rule with several recipients is deliberate: apps/base/ is shared by both clusters, so a Secret there has to decrypt on each of them. The example Secret the prompt names goes in apps/base/podinfo/secret.yaml, encrypted with sops --encrypt --in-place, and is added to that directory's kustomization.yaml; release.yaml gains valuesFrom pointing at it, so the chart reads the values through the Secret rather than from the inline block.
Decryption is configured where the manifests are applied. Both apps Kustomizations, in clusters/staging/apps.yaml and clusters/production/apps.yaml, get decryption: {provider: sops, secretRef: {name: sops-age}}; infra-configs gets the same block only if the prompt puts a secret under infrastructure/. The private keys never enter Git: the README gains a section with age-keygen -o age.agekey, the kubectl create secret generic sops-age --namespace=flux-system --from-file=age.agekey=age.agekey command for each cluster, and the note that the data key must end in .agekey for the kustomize-controller to read it as an age identity. For CI, e2e.yaml gains a step before flux create kustomization that writes the sops-age Secret from a repository secret named SOPS_AGE_KEY, the private half of the third recipient, so the kind cluster can decrypt what the workflow reconciles.
In its sandbox the agent installs sops and age, generates a throwaway key to prove the round trip on a copy of the Secret, then encrypts the committed file with the real recipients only, and reads the sops block in the output to confirm the three age entries and a mac. It runs scripts/validate.sh against the repository and kustomize build on apps/staging and apps/production, and keeps the output. The sandbox has no cluster, so the agent does not run kind itself; the repository's e2e workflow runs on every pushed branch, which is where the decryption is exercised end to end, and the pull request says to add SOPS_AGE_KEY under the repository's Actions secrets before that run can pass.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add SOPS-encrypted secrets with age to this Flux repository. Read README.md, .fluxschema.yml, .sourceignore, scripts/validate.sh, both GitHub workflows, every file under clusters/, apps/ and infrastructure/ first. Add a root .sops.yaml with one creation rule for apps/ and infrastructure/, encrypted_regex ^(data|stringData)$, and three age recipients: staging <age public key>, production <age public key>, and CI <age public key>. Add an encrypted Secret named podinfo-values in apps/base/podinfo/ holding values the podinfo chart reads, list it in that kustomization.yaml and reference it from release.yaml with valuesFrom. Add decryption with provider sops and secretRef sops-age to the apps Kustomization in both clusters. Do not commit any private key; document age-keygen and the kubectl create secret command with the .agekey suffix in the README. Add a step to the e2e workflow that creates the sops-age Secret in flux-system from a SOPS_AGE_KEY repository secret before the Kustomization is created. Prove the encryption round trip with a throwaway key in the sandbox, run scripts/validate.sh and kustomize build on both overlays, include the output, and open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- 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 that adds .sops.yaml and apps/base/podinfo/secret.yaml, changes apps/base/podinfo/kustomization.yaml and release.yaml, clusters/staging/apps.yaml, clusters/production/apps.yaml, .github/workflows/e2e.yaml and README.md. .fluxschema.yml, .sourceignore and scripts/validate.sh are unchanged because they already handle the sops field.
The description shows the encrypted file's sops metadata with its three recipients, quotes the validate.sh and kustomize build output, and lists the two operator steps the repository cannot do for itself: creating the sops-age Secret on each cluster and adding SOPS_AGE_KEY to Actions. The commands and their full output are in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a reviewer creates those secrets, checks the e2e workflow result on the branch, and decides whether production should share a recipient list with staging or get its own rule. A follow-up message to the same session can split the rules per cluster, add sops updatekeys instructions for rotation, or move the first real credential into the new file.
Run it on every GitOps repository that still keeps secrets outside Git
A platform team with several cluster repositories sends one POST /o/{org}/sessions per repository, this prompt as input with that repository's public keys, and the repository in resources. Each run reads its own Kustomizations and sources, so a repository that syncs from a GitRepository path rather than an ArtifactGenerator gets decryption on the Kustomizations it actually has.
Send a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run it already started. The key's webhook_url reports when each run the key starts finishes, with session_url for the pull request link and the validation output.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
SOPS in Flux is a handful of files that all have to agree: the creation rule's regex, the recipients, the Secret's data keys, the Kustomization's decryption, the .agekey suffix on the cluster Secret, and the CI key that lets the e2e job decrypt what it reconciles. The agent reads the repository's structure and its existing skipJSONPath for sops, and proves the round trip and the overlays in a sandbox of its own, with the output kept.
The pull request carries the rule, the encrypted file, the decryption config and the workflow change together, so a reviewer sees the whole mechanism at once instead of a secret that decrypts on one cluster and not the other. Several repositories can be done at once, each in its own sandbox with its own pull request.
Frequently asked questions
Does a private key ever go into Git?
No. The repository holds only public recipients in .sops.yaml and ciphertext in the Secret. Private keys live in the sops-age Kubernetes Secret on each cluster, created by hand with the command in the README, and in the SOPS_AGE_KEY Actions secret for CI.
Why one rule with three recipients?
apps/base/ is reconciled by both clusters, so a file there must decrypt on each; listing every recipient on one rule keeps sops from producing a file one cluster cannot read. Per-cluster rules make sense for files under apps/staging/ or apps/production/ only, and the agent can split them if you ask.
Will the e2e workflow still pass?
Once SOPS_AGE_KEY exists in the repository's Actions secrets. The new step creates the sops-age Secret in flux-system before the Kustomization is created, so the kind cluster decrypts the Secret like a real cluster would. Without that repository secret the apps Kustomization reports a decryption error and the wait step times out.
Can I use a cloud KMS instead of age?
Yes. The decryption block keeps provider: sops, and for GCP, AWS or Azure keys the serviceAccountName field lets the kustomize-controller authenticate without a stored credential. Say which KMS you use and the agent writes the creation rule and the service account annotation for it.
How do I rotate a key?
Add the new public key to .sops.yaml, run sops updatekeys on each encrypted file so it is re-encrypted for the new recipient list, update the sops-age Secret on the cluster, then remove the old key and run updatekeys again. The README section the agent writes includes those steps.