# Publish Manifests as OCI Artifacts for Flux

Yes. An agent adds a workflow that pushes your manifests with `flux push artifact`, points each cluster at an OCIRepository, tests the push locally and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-oci-artifacts/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 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`

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

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

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.

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

## More Flux jobs

- [Add Slack Alerts to a Flux GitOps Repository](https://getrush.ai/run/add-slack-alerts/flux/)
- [Add SOPS-Encrypted Secrets to a Flux GitOps Repository](https://getrush.ai/run/add-sops-secrets/flux/)
- [Add Tenant Isolation to a Flux Repository](https://getrush.ai/run/add-tenant-isolation/flux/)

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

- [Set Up SQLx Offline Mode So a Rust App Builds Without a Database](https://getrush.ai/run/add-offline-mode/sqlx/)
- [Add an SQLx Offline Query Check to CI](https://getrush.ai/run/add-offline-query-check-to-ci/sqlx/)
- [Show Online Users in a Socket.IO Chat](https://getrush.ai/run/add-online-users/socket-io/)

## 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/)
