What the agent does
The agent reads how each cluster is fed before it changes the source, because in a Flux repository the source is referenced from several places. In a layout like fluxcd/flux2-kustomize-helm-example, clusters/staging/artifacts.yaml holds an ArtifactGenerator from source.extensions.fluxcd.io/v1beta1 with one source, alias monorepo, of kind GitRepository named flux-system; it cuts the repository into two artifacts, infrastructure from infrastructure/** and apps from apps/base/** and apps/staging/**. clusters/staging/infrastructure.yaml defines the infra-controllers and infra-configs Kustomizations with sourceRef.kind: ExternalArtifact, and clusters/staging/apps.yaml defines apps the same way with path: ./staging, interval: 1h, prune: true and wait: true; clusters/production/ repeats the pattern with its own values and a patch on the letsencrypt ClusterIssuer. apps/base/podinfo/release.yaml is a HelmRelease from helm.toolkit.fluxcd.io/v2 whose chart comes from a HelmRepository, and infrastructure/controllers/ already pulls the cert-manager and Envoy Gateway charts from OCIRepository sources, so the cluster can already reach a registry. .sourceignore includes only apps/, clusters/ and infrastructure/. .github/workflows/test.yaml validates the manifests with the Flux schema action and runs flux migrate -f . --yes to catch deprecated API versions; e2e.yaml boots a kind cluster, runs flux install --components-extra source-watcher, creates a Git source for the branch and waits for the Kustomizations and the HelmRelease.
The Flux OCI documentation describes the shape the agent follows: a CI job runs flux push artifact oci://<registry>/<org>/manifests/<repo>:<tag> with --path, --source set to the Git URL and --revision in the form <branch>@sha1:<commit>, then flux tag artifact adds a moving tag such as staging; on the cluster an OCIRepository with ref.tag pulls it and is used in the same way as a GitRepository. The artifact uses Flux's own media types, so a registry that accepts custom OCI media types works, and GitHub Container Registry is named among them. The ArtifactGenerator specification lists OCIRepository among the source kinds it accepts, which is what lets the cut into infrastructure and apps stay as it is.
The agent adds .github/workflows/push-artifact.yaml, written from the example in the Flux GitHub Action documentation and the pinned action versions the repository already uses: permissions: packages: write, actions/checkout@v7, fluxcd/flux2/action@main as e2e.yaml uses it, and docker/login-action with github.actor and GITHUB_TOKEN against ghcr.io. On a push to main it pushes apps/ and infrastructure/ under the short commit SHA, with --ignore-paths set from .sourceignore so the same files travel as before, then tags that digest staging; on a pushed semver tag the same job tags it production. In clusters/staging/ a new manifests.yaml declares an OCIRepository named manifests in flux-system with url: oci://ghcr.io/<owner>/manifests/<repo>, ref.tag: staging, interval: 5m, provider: generic and a secretRef to ghcr-auth, because a GitHub package is private until someone makes it public; artifacts.yaml changes its one source to kind: OCIRepository, name: manifests, and nothing else in the Kustomizations moves, since they read the generated ExternalArtifact. Production gets the same file with ref.tag: production. The GitRepository named flux-system stays, because clusters/ itself still comes from Git through the bootstrap sync.
Then the agent proves the push works before asking anyone to merge it. The sandbox has no Docker, so it installs it first with sudo apt-get install -y docker.io, starts dockerd, and runs a local registry:2 container; it runs the workflow's flux push artifact line against that registry with --insecure-registry, pulls the result with flux pull artifact and compares it with the working tree using flux diff artifact, keeping each command's output. It runs the repository's own flux migrate -f . --yes to confirm the new files use current API versions, and writes the image pull secret step into the pull request as a command for the reader, flux create secret oci ghcr-auth --url=ghcr.io --username=<user> --password=<token> on each cluster, since a token for the reader's registry is not something the run has. The e2e.yaml workflow, which creates its own Git source for the branch under test, keeps working unchanged and the pull request explains why: the e2e cluster never reads artifacts.yaml from the registry.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Switch this Flux repository's application and infrastructure manifests from a Git source to OCI artifacts. Read the README, .sourceignore, every file under clusters/, apps/ and infrastructure/, and the workflows under .github/workflows/ first. Add .github/workflows/push-artifact.yaml that on a push to the default branch logs in to GitHub Container Registry with the workflow token and runs flux push artifact for the manifest directories with --source and --revision set from Git, tagged with the short commit SHA, then flux tag artifact with a staging tag; on a semver tag push, tag it production. Add an OCIRepository per cluster that pulls that tag with a secretRef for the registry secret, and point each cluster's ArtifactGenerator or Kustomizations at it instead of the GitRepository, leaving the bootstrap GitRepository in place. Install Docker in the sandbox, start a local registry, run the push and pull commands against it with --insecure-registry and flux diff artifact, and run flux migrate -f . --yes. Open a pull request with the commands, their output and the flux create secret oci command the reader must run on each cluster.",
"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
The pull request adds .github/workflows/push-artifact.yaml and clusters/staging/manifests.yaml and clusters/production/manifests.yaml, and changes artifacts.yaml in both cluster directories. Its description quotes the flux push artifact and flux diff artifact output from the local registry run, the flux migrate result, and the exact flux create secret oci command per cluster with the token left for the reader. The Kustomizations in apps.yaml and infrastructure.yaml are untouched, because they read the artifacts the generator produces and the generator's source is the only thing that changed.
A reviewer checks the artifact repository path, whether the package should be public so no pull secret is needed, whether the production tag should come from flux tag artifact or from ref.semver on the production OCIRepository, which the pull request offers as the alternative, and the interval on each OCIRepository. After merging, the first push to the default branch publishes the first artifact, and the staging cluster picks it up once the secret exists; until then the OCIRepository reports why it cannot pull in its Ready condition, which the pull request tells the reader to check with flux get sources oci.
Run it on every Flux repository still synced from Git
A platform team with a repository per cluster group sends this body once per repository from its own server, each POST /o/{org}/sessions naming one repository in resources and carrying a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own cluster directories: a repository whose Kustomizations reference the GitRepository directly, with no ArtifactGenerator, gets its sourceRef fields changed instead, and a repository that already pushes artifacts for one cluster gets the others added to the same workflow.
The key's webhook_url reports each run the key starts with the pull request URL in result, so a script that sent the requests collects the pull requests without polling.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Whether an artifact push works depends on flags that are easy to get subtly wrong: which paths go in, what --revision must look like, and whether the artifact that comes back matches the tree. The agent runs the real flux commands against a registry it started in its own sandbox, diffs the pulled artifact against the working tree and keeps every command and its output in the run's record, so the pull request carries evidence from the Flux CLI rather than a workflow nobody has executed.
The change is shaped by the repository's own layout, read from its files: the cut into infrastructure and apps stays because the generator accepts an OCIRepository source, the bootstrap GitRepository stays because clusters/ still comes from Git, and the workflow reuses the action versions the test and e2e workflows already pin. Five repositories get five pull requests, each with its own registry path and cluster files.
Frequently asked questions
Do I have to stop using Git as a source?
No. The bootstrap GitRepository that syncs clusters/ stays, and only the application and infrastructure manifests move to the registry. The Flux documentation describes the artifact as a GitRepository substitute, usable from the same Kustomization, Alert and Receiver resources.
Which registries work?
The Flux OCI documentation names Docker Hub, GitHub and GitLab container registries, ACR, ECR, GAR, Harbor and any registry that accepts custom OCI media types. The workflow targets GitHub Container Registry because the repository's own token can push there; the registry URL is one variable at the top of the file.
How does the cluster authenticate to the registry?
With an image pull secret referenced from the OCIRepository through secretRef, created with flux create secret oci on each cluster; the pull request includes the command with the token left out. On AWS, Azure or Google, provider can name the cloud so the controller uses its IAM identity instead, which the pull request mentions as the alternative.
Will the end-to-end workflow still pass?
Yes. e2e.yaml creates a Git source for the branch under test and reconciles clusters/staging from it; it does not read the registry. The pull request notes this so a reviewer knows the e2e run exercises the cluster files but not the new artifact path, which the first real push on the default branch does.
How do I roll back a bad artifact?
Tag an earlier commit's artifact staging again with flux tag artifact, or set ref.digest on the OCIRepository to pin one. Nothing in the cluster files has to change for the first option, which is why the pull request uses moving tags rather than editing a tag in Git on every release.