# Add SOPS-Encrypted Secrets to a Flux GitOps Repository

Yes. An agent adds a .sops.yaml with age recipients, an encrypted Secret, decryption on your Flux Kustomizations and a CI key, validates it all, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-sops-secrets/flux/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

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.phoenix.so/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 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.

## 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.

## More Flux jobs

- [Add Tenant Isolation to a Flux Repository](https://getrush.ai/run/add-tenant-isolation/flux/)
- [Add a GitHub Webhook Receiver to a Flux Cluster](https://getrush.ai/run/add-webhook-receiver/flux/)
- [Review Flux Manifest Changes in Pull Requests](https://getrush.ai/run/review-kubernetes-manifests/flux/)

## More jobs like this: Hand off a long task

- [Add Source Freshness Checks to a dbt Project](https://getrush.ai/run/add-source-freshness/dbt/)
- [Add a Splash Screen to an Electron App](https://getrush.ai/run/add-splash-screen/electron/)
- [Add SpotBugs to a Maven Build](https://getrush.ai/run/add-spotbugs/maven/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
