Publish Releases from CI
Publish every build as a tagged artifact that a ReleaseSource picks up as a new release. Pick one tagging scheme, publish with the matching workflow, and give the ReleaseSource the policy that orders those tags.
On this page
Each artifact also carries two OCI annotations: org.opencontainers.image.revision (the full git commit SHA) and org.opencontainers.image.source (the repository URL). Kuberik reads them to link a release to its commit and pull request, so revision must be the SHA, not a version string.
Tag every build on main
Tag each build main-<short sha>-<commit timestamp> so that every commit to main becomes a release, ordered by when it was committed. This workflow builds the image, tags it, and annotates the image index.
name: Build
on:
push:
branches:
- main
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to the container registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
env:
DOCKER_METADATA_ANNOTATIONS_LEVELS: index # Kuberik reads the index
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=raw,value=main-{{sha}}-{{commit_date 'X'}}
annotations: |
org.opencontainers.image.source=${{ github.event.repository.html_url }}
org.opencontainers.image.revision=${{ github.sha }}
- name: Build and push
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
annotations: ${{ steps.meta.outputs.annotations }}The ReleaseSource keeps only tags of that shape, extracts the timestamp, and orders by it as a number, so the newest commit is the newest release.
apiVersion: kuberik.com/v1alpha1
kind: ReleaseSource
metadata:
name: hello-world
namespace: hello-world
spec:
oci:
image: ghcr.io/acme/hello-world
filterTags:
pattern: '^main-[a-f0-9]+-(?P<ts>[0-9]+)$'
extract: '$ts'
policy:
numerical:
order: asc # highest timestamp winsTag releases by version
Publish only when someone pushes a git tag such as v1.4.0, when you want to choose which commits become releases. The image gets the version without the v: 1.4.0.
name: Release
on:
push:
tags:
- "v*"
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to the container registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
env:
DOCKER_METADATA_ANNOTATIONS_LEVELS: index # Kuberik reads the index
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=semver,pattern={{version}}
annotations: |
org.opencontainers.image.source=${{ github.event.repository.html_url }}
org.opencontainers.image.revision=${{ github.sha }}
- name: Build and push
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
annotations: ${{ steps.meta.outputs.annotations }}Order these tags by semantic version. The range keeps pre-releases such as 1.5.0-rc.1 out.
apiVersion: kuberik.com/v1alpha1
kind: ReleaseSource
metadata:
name: hello-world
namespace: hello-world
spec:
oci:
image: ghcr.io/acme/hello-world
policy:
semver:
range: ">=1.0.0"Publish rendered manifests
When Kuberik moves rendered manifests instead of an image tag, build the image, render each environment’s overlay in CI, and push the result as an OCI artifact with the Flux CLI. This workflow builds the image from the Dockerfile at the repository root, pins its tag in every overlay under deploy/, and pushes one artifact per overlay, named after its directory. The image and every artifact carry the same main-<sha>-<timestamp> tag.
name: Manifests Release
on:
push:
branches:
- main
env:
REGISTRY: ghcr.io
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Resolve image and version
id: v
run: |
echo "image=${REGISTRY}/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT" # ghcr.io needs lowercase
echo "version=main-${GITHUB_SHA::7}-$(git log -1 --format=%ct)" >> "$GITHUB_OUTPUT"
- name: Install the Flux CLI
uses: fluxcd/flux2/action@main
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to the container registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push the image
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.v.outputs.image }}:${{ steps.v.outputs.version }}
- name: Render and push manifests
env:
IMAGE: ${{ steps.v.outputs.image }}
VERSION: ${{ steps.v.outputs.version }}
run: |
set -euo pipefail
for dir in deploy/*/; do
env="$(basename "$dir")"
[ "$env" = base ] && continue # shared base, not an environment
(cd "$dir" && kustomize edit set image "${IMAGE}:${VERSION}")
out="$(mktemp -d)"
kustomize build "$dir" -o "$out"
flux push artifact \
"oci://${IMAGE}/${env}/manifests:${VERSION}" \
--path "$out" \
--source="${{ github.event.repository.html_url }}" \
--revision="${{ github.sha }}"
doneEvery directory under deploy/ except base is an environment’s overlay: a directory with a kustomization.yaml whose Deployment names the image ghcr.io/acme/hello-world without a tag; kustomize edit set image adds the build’s tag before the render. With deploy/development, deploy/staging and deploy/production, the workflow pushes three artifacts; with only deploy/production, it pushes one. flux push artifact sets the source and revision annotations from --source and --revision.
Each environment’s ReleaseSource scans its own artifact with the same timestamp policy as an image. This one is for production:
apiVersion: kuberik.com/v1alpha1
kind: ReleaseSource
metadata:
name: hello-world
namespace: hello-world
spec:
oci:
image: ghcr.io/acme/hello-world/production/manifests
filterTags:
pattern: '^main-[a-f0-9]+-(?P<ts>[0-9]+)$'
extract: '$ts'
policy:
numerical:
order: asc # highest timestamp winsThe Flux OCIRepository that Kuberik drives points at the same artifact; see Deploy Your First App.
Pull from a private registry
Every scheme above works with a private registry. Point the ReleaseSource’s spec.oci.secretRef at a kubernetes.io/dockerconfigjson Secret in its namespace.
kubectl create secret docker-registry ghcr-pull -n hello-world \
--docker-server=ghcr.io --docker-username=<your-user> --docker-password=<your-token>
kubectl patch releasesource hello-world -n hello-world --type merge \
-p '{"spec":{"oci":{"secretRef":{"name":"ghcr-pull"}}}}'For rendered manifests, the Flux OCIRepository pulls the artifact itself and takes the same Secret in its spec.secretRef.
kubectl patch ocirepository hello-world -n hello-world --type merge \
-p '{"spec":{"secretRef":{"name":"ghcr-pull"}}}'Check the result
After the workflow runs, the ReleaseSource lists the new tag as its newest release, with the commit it read from the annotations.
kubectl get releasesource -n hello-world hello-world -o jsonpath='{.status.newest}'{"created":"2026-11-13T15:20:00Z","revision":"3f9c2ab0d1e84b6f9a7c5e2d4b1a8f6c3e9d0b7a","tag":"main-3f9c2ab-1794583200"}On the dashboard’s Apps page, the app’s card names the newest build. Publishing only makes it a release: here a deployment window still holds it.


If the tag is missing, compare it with filterTags.pattern: tags that do not match are not releases. If revision is missing, the annotations were written to the per-platform manifests instead of the image index.
Troubleshoot
The ReleaseSource reports its state in Ready, SourceReachable and Syncing.
kubectl get releasesource hello-world -n hello-world \
-o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'| Symptom | Cause | Fix |
|---|---|---|
Ready=False, reason ConfigInvalid | The spec cannot be used. The message names the field. | Fix the spec and apply it again. |
SourceReachable=False, reason Unreachable, with Ready=True, reason Stale | The registry did not answer. The last catalogue is still served. | Check the image path and registry credentials. |
Ready=False, reason SourceUnreachable | The registry failed for three sync intervals, or no catalogue exists yet. | Check the image path and registry credentials. |
Syncing=True, reason ResolveBudget | Tags are still being resolved. The message counts them. | Wait. |
| A tag is missing | The tag was skipped, or its metadata was rejected or could not be resolved. Events TagsSkipped, MetadataRejected and TagUnresolvable name it. | Read the Events below. |
kubectl events -n hello-world --for releasesource/hello-worldNext steps
- Get started Deploy Your First App Deploy an app with a Rollout, a ReleaseSource and Flux, then watch Kuberik ship a new release.
- Concepts Propagation Modes Move an image tag or rendered manifests through your environments.
- Ship releases Promote Across Environments Deploy to production only after staging has shipped the same release.