Promoting Non-Image Artifacts with Kargo by Shipping Them as OCI
Our static sites were already following build once, promote forward, the idea I wrote about in Build Once. Promote Forward. Ship Daily.. CI built the site once and uploaded the result to an S3 artifact bucket. Promoting meant taking that same artifact and deploying it to the next environment’s bucket, which is served behind a CDN.
It worked. But it ran on custom GitHub Actions scripts, separate from how everything else was deployed.
Meanwhile, our services were moving to Kargo, which I covered in Build Once, Promote Forward with Kargo. The point of that migration was to standardize deployment: one promotion path, one place to see what’s running where, one approval flow. Leaving the static sites on their own scripts would defeat the purpose.
The artifact was in the wrong place
The promotion model wasn’t the problem. Where the artifact lived was.
A Kargo Warehouse discovers new artifacts by watching registries and Git repositories. It can’t subscribe to an S3 bucket. As long as the builds were sitting in the artifact bucket, Kargo couldn’t see them, they never became Freight, and there was nothing to promote.
So the question was how to put the build somewhere Kargo already knows how to watch.
The trick: ship it the OCI way
A container registry isn’t only for container images. Any OCI registry, including ECR, can store arbitrary artifacts as long as they’re pushed in the OCI format. ORAS is a small CLI built for exactly that.
So the change in CI was small. Instead of uploading the build to the S3 artifact bucket, it pushes the same tarball to ECR, tagged with the short Git SHA:
aws ecr get-login-password --region us-east-1 \
| oras login "$ECR_REGISTRY" -u AWS --password-stdin
oras push "$ECR_REGISTRY/frontend:$SHORT_SHA" \
--artifact-type application/vnd.example.frontend.dist.v1 \
--annotation "org.opencontainers.image.revision=$FULL_SHA" \
--annotation "org.opencontainers.image.version=$VERSION" \
dist.tgz:application/vnd.oci.image.layer.v1.tar+gzip
The custom --artifact-type marks this as a frontend build, not a container image, so nothing can confuse the two. The annotations carry the full commit and version along with the artifact, which comes in handy later when the deploy reports what it shipped.
That’s the whole trick. To Kargo, this is just another tag in an ECR repository. A Warehouse image subscription discovers it the same way it discovers a container image, which I tested in A Small Kargo Warehouse POC with GHCR. Each new build becomes Freight, and the static sites show up in the Kargo UI next to the services, with the same stages, history and approvals.
There’s a nice side effect, too. A file in a bucket can be overwritten. Our ECR tags are immutable and every artifact is addressed by digest, so the thing that gets promoted is exactly the thing CI pushed. Since it’s a standard OCI artifact, CI also mirrors it to Google Artifact Registry with a single oras cp and checks that both digests match.
Getting it out of the registry
Discovery was only half the problem. Promoting an image means changing a tag and letting Argo CD roll out a new pod. Promoting a static site means pulling the tarball, uploading it to the environment’s bucket and invalidating the CDN cache. Something has to run those commands, and before, that something was GitHub Actions.
Open source Kargo doesn’t have a step for that. I checked the v1.11 source. Running your own container during a promotion (custom-steps) is a commercial Akuity Platform feature, and so is handing work to a CI pipeline with gha-dispatch-workflow. The open source build can update Git and watch Argo CD, but it can’t run aws s3 sync.
Kargo can’t run a script, but Argo CD can create a Kubernetes Job, and Kargo already knows how to wait on an Argo CD application. So the deploy goes into the site’s Helm chart as a Job:

This is where the standardization pays off. The promotion task doesn’t change at all. The same shared task we use for container images updates the tag in a values file, syncs the Argo CD application and waits for it to become healthy. Kargo never learns that this application is a static site. That knowledge lives in the chart.
The deploy Job needs nothing extra
You’d expect the deploy Job to use oras pull. It doesn’t. It runs in the stock amazon/aws-cli image with a deploy script mounted from a ConfigMap, and no custom image at all.
That image has aws, python3, curl and coreutils. It doesn’t have oras, jq, or even tar and gzip. Instead of building and maintaining a deployer image, the script pulls the artifact through the ECR API:
- Read the manifest and check its
artifactType, so it never tries to deploy something that isn’t a frontend build. - Download the single layer and check its sha256 against the manifest.
- Unpack it with Python’s
tarfile, which refuses unsafe paths and links. - Sync the files to the environment’s bucket and invalidate the CDN.
If anything fails in the first three steps, the script stops before writing anything to S3. When it finishes, it prints one JSON line with the environment, tag, commit, version and outcome, read straight from the manifest annotations CI added.
Make the deploy Job a Sync hook
My first version was a plain Job named after the tag. A failed Job marked the application Degraded, which failed the promotion, and it looked done.
Then I retried a failed promotion of the same tag, and nothing happened. The values file already had that tag, so there was nothing to commit, and the failed Job was still sitting in the cluster. Argo CD had nothing new to create, and argocd-wait sat there until its 10-minute timeout.
The fix is to make the Job an Argo CD Sync hook:
metadata:
name: deploy-{{ .Values.image.tag }}
annotations:
argocd.argoproj.io/hook: Sync
argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
argocd.argoproj.io/sync-wave: "1"
spec:
backoffLimit: 0
ttlSecondsAfterFinished: 86400
A hook is created on every sync instead of being reconciled against Git, and BeforeHookCreation deletes the old one first. Since Kargo always triggers a sync, retrying the same tag now runs a fresh Job. In my test, a retried failure showed up in about a minute instead of after the 10-minute timeout.
backoffLimit: 0 is on purpose. Kubernetes shouldn’t quietly retry a deploy. A retry should be a new promotion that shows up in Kargo.
Two more things I learned the hard way:
- Hooks pile up. Argo CD doesn’t prune hooks, and every tag leaves a finished Job behind.
ttlSecondsAfterFinishedcleans each one up a day later, which still leaves time to read the logs of a recent failure. - Don’t ship a chart that only has the hook. If the hook is the only thing the chart renders, Argo CD has nothing to track, and with automated sync its safety check can refuse to run a sync that “will wipe out all resources.” The ConfigMap holding the deploy script and the environment’s settings solves that. The
sync-wave: "1"on the Job makes sure the ConfigMap exists before the Job mounts it.
What we got out of it
We already had build once, promote forward for the static sites. What changed is that it’s no longer a special case:
- One promotion path. Static sites and services sit side by side in Kargo, with the same history and approval flow, instead of one living in Kargo and the other in GitHub Actions scripts.
- Less custom code. The shared promotion task covers both. The only static-site-specific piece is a deploy script in the chart, running in a stock image.
- CI doesn’t hold deploy credentials. CI builds and pushes to ECR, and that’s it. The deploy Job runs with a workload identity scoped to its environment.
- A failed deploy fails the promotion. You see it where the release happens, not in a CI log someone has to remember to check.
The only real change to the artifact was where it lives. Moving it from an S3 bucket to ECR was enough to make a static site look like everything else Kargo promotes. If an artifact can live in an OCI registry, Kargo can promote it. Argo CD runs the deploy, and Kargo waits on the result.