Ship releases

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
  1. Tag every build on main
  2. Tag releases by version
  3. Publish rendered manifests
  4. Pull from a private registry
  5. Check the result
  6. Troubleshoot
  7. Next steps

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.

.github/workflows/build-main.yamlYAML
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.

releasesource.yamlYAML
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 wins

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

.github/workflows/release.yamlYAML
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.

releasesource.yamlYAML
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.

.github/workflows/manifests-release.yamlYAML
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 }}"
          done

Every 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:

releasesource.yamlYAML
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 wins

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

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

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

Terminal
kubectl get releasesource -n hello-world hello-world -o jsonpath='{.status.newest}'
OutputJSON
{"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.

The billing-edge card on the Apps page: the newest build, 5.8.0-62, held by the Business hours deploy window, with staging and production both heldThe billing-edge card on the Apps page: the newest build, 5.8.0-62, held by the Business hours deploy window, with staging and production both held

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.

Terminal
kubectl get releasesource hello-world -n hello-world \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'
SymptomCauseFix
Ready=False, reason ConfigInvalidThe spec cannot be used. The message names the field.Fix the spec and apply it again.
SourceReachable=False, reason Unreachable, with Ready=True, reason StaleThe registry did not answer. The last catalogue is still served.Check the image path and registry credentials.
Ready=False, reason SourceUnreachableThe registry failed for three sync intervals, or no catalogue exists yet.Check the image path and registry credentials.
Syncing=True, reason ResolveBudgetTags are still being resolved. The message counts them.Wait.
A tag is missingThe tag was skipped, or its metadata was rejected or could not be resolved. Events TagsSkipped, MetadataRejected and TagUnresolvable name it.Read the Events below.
Terminal
kubectl events -n hello-world --for releasesource/hello-world

Next steps