Community Perk$300 in Akamai Cloud credits for buildersClaim your credits

GitOps for Spin Apps with SpinKube, Flux and GitHub Actions

Every time I demonstrate SpinKube, someone asks: “Nice, but how do I get this into our existing deployment pipeline?” The short answer: Spin apps don’t need a special pipeline, they ship the same way as every other workload in your cluster.

In this article, I’ll show you the longer answer, using GitOps with Flux: the Spin app and its SpinApp manifest live in one Git repository, a GitHub Actions workflow bumps the image tag on every push, and Flux rolls out whatever Git says.

The demo repository: Spin app, SpinApp manifest, Flux config and CI workflowakamai-developers/gitops-for-spin-apps

What You Need To Follow Along

You need a Kubernetes cluster with SpinKube installed. For a local setup, follow the SpinKube Quickstart, as I won’t repeat those steps here. On top of that, you need:

Personally, I use Homebrew to manage software on my Mac, so installing spin, flux and gh is a one-liner, followed by logging in to GitHub:

# Install spin, gh and flux
brew install spinframework/tap/spin gh fluxcd/tap/flux

# Authenticate against GitHub
gh auth login

Creating The Repository And The Spin App

Both Flux and the CI pipeline will push to a Git repository, so you need one you own. Create the repository with gh and scaffold the app at its root. I use the TypeScript HTTP template here, but any Spin template works:

# Create a new repo
gh repo create gitops-for-spin-apps --public --clone

cd gitops-for-spin-apps

# Create a new Spin application 
spin new -t http-ts hello --accept-defaults --output .

I keep app code and deployment config together here. Many teams split them into two repositories, so that a smaller group controls what runs in the cluster, but for a single app one repository is simpler, and the GitOps flow is the same.

If you’d rather skip straight to the finished state, fork the repository linked above instead.

Installing Flux Into The Cluster

A GitHub Token For Flux

flux bootstrap needs a personal access token (PAT) to push its manifests to your repository. With --token-auth, the controllers in the cluster use the same token to pull from the repository over HTTPS, so Flux stores it as a Secret in the flux-system namespace.

Create a fine-grained PAT restricted to your repository, give it a sensible expiry, and grant these repository permissions:

  • Administration: read-only
  • Contents: read and write
  • Metadata: read-only

Then export it in your shell:

# Set your GitHub PAT
export GITHUB_TOKEN=<your-token>

You could use gh auth token instead, but that’s the token of your whole gh session. It carries far more permissions than Flux needs, and it stops working when you log out of gh. A dedicated token is easier to scope, rotate and revoke.

Running flux bootstrap

flux bootstrap installs Flux into the cluster, commits its own manifests to clusters/dev/flux-system, and creates a GitRepository named flux-system that points at your repository:

# Bootstrap Flux
flux bootstrap github \
  --token-auth \
  --owner=<your-github-user> \
  --personal \
  --repository=gitops-for-spin-apps \
  --branch=main \
  --path=./clusters/dev

# Pull latest from origin
git pull

If the repository belongs to an organization, pass the organization as --owner and drop --personal. The git pull fetches the commit Flux just made.

Generating The SpinApp Manifest

The kube plugin for the Spin CLI scaffolds the SpinApp from an image reference, so you don’t have to write it by hand:

# Update the plugin feed
spin plugins update

# Install the kube plugin for spin
spin plugins install kube --yes

# Create the deployment folder
mkdir -p deploy/hello

# Scaffold the SpinApp manifest
spin kube scaffold --from "ghcr.io/<your-github-user>/hello:v1" \
  --out deploy/hello/spinapp.yaml

The result looks like this:

apiVersion: core.spinkube.dev/v1alpha1
kind: SpinApp
metadata:
  name: hello
spec:
  image: "ghcr.io/<your-github-user>/hello:v1"
  executor: containerd-shim-spin
  replicas: 2

The executor refers to the SpinAppExecutor installed with SpinKube. spin kube scaffold has flags for most other fields, such as --replicas, --variable or --image-pull-secret.

Next to it, a plain deploy/hello/kustomization.yaml lists the file:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - spinapp.yaml

Telling Flux What To Deploy

Because app and config share a repository, there’s no need for a second GitRepository. The flux-system source created by bootstrap already tracks it. A Flux Kustomization in clusters/dev/hello.yaml tells Flux which path to apply:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: hello
  namespace: flux-system
spec:
  interval: 5m
  path: ./deploy/hello
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  targetNamespace: default

prune: true makes Git the source of truth in both directions: Flux creates what you add to deploy/hello/, and deletes what you remove from it. Delete spinapp.yaml from the repository, and Flux removes the SpinApp from the cluster.

Flux already reconciles everything under clusters/dev, so committing this file registers the app. Don’t commit yet, though: hello:v1 isn’t in the registry so far.

Shipping The First Version

Logging In To ghcr.io

Pushing to GitHub Container Registry requires a token with the write:packages scope. Fine-grained tokens don’t work with ghcr.io, so the Flux token won’t do. Add the scope to your gh login and hand its token to spin registry login:

# Ensure the current token of gh has write:packages scope
gh auth refresh -h github.com -s write:packages

# Authenticate spin CLI
gh auth token | spin registry login ghcr.io \
  -u <your-github-user> --password-stdin

Then build and push the first version:

# Build the Spin app
spin build

# Push it to ghcr.io
spin registry push ghcr.io/<your-github-user>/hello:v1

Making The Image Public

GitHub creates new packages as private, and your cluster has no credentials for ghcr.io. For this demo, make the package public. Open the hello package on GitHub (your profile’s or organization’s Packages tab), go to Package settings, and in the Danger Zone choose Change visibility and Public.

To check that anonymous pulls work, ask ghcr.io for a pull token without credentials. A public package returns a token instead of an error:

curl -s "https://ghcr.io/token?scope=repository:<your-github-user>/hello:pull"

For real workloads, keep the package private and give the cluster a pull secret instead, using spin kube scaffold --image-pull-secret.

Deploying With git push

With the image in place, commit and push:

# Commit & Push to GitHub
git add . 
git commit -m "hello: initial version"
git push

Flux picks up the change and creates the SpinApp; spin-operator turns it into a Deployment. Watch it with:

# See flux deploying the hello app
flux get kustomizations --watch
kubectl get spinapp hello

Once the SpinApp is ready, spin-operator has also created a Service named hello. Forward a local port to it and call the app:

# Forward local port 8080 to the hello service
kubectl port-forward svc/hello 8080:80

# In a second terminal, call the app
curl localhost:8080

Automating Releases With GitHub Actions

So far, you built and pushed the image by hand. From now on, a GitHub Actions workflow does that on every push to main:

git push app code CI build + push OCI registry hello:<sha> deploy/ SpinApp YAML Flux reconciles SpinApp spin-operator Shim containerd CI bumps the tag under deploy/. Flux applies the commit and the operator rolls out the new version. pull image update reconcile

The workflow builds the app, pushes it tagged with the short commit SHA, and bumps the tag in deploy/hello/spinapp.yaml. Flux takes it from there. Put it into .github/workflows/release.yml:

name: Release

on:
  push:
    branches: [main]
    paths-ignore:
      - "deploy/**"
      - "clusters/**"

permissions:
  contents: write
  packages: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - uses: fermyon/actions/spin/setup@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Build and push the app
        run: |
          IMAGE="ghcr.io/${{ github.repository_owner }}/hello:${GITHUB_SHA::7}"
          echo "IMAGE=$IMAGE" >> "$GITHUB_ENV"
          spin build
          echo "${{ secrets.GITHUB_TOKEN }}" | spin registry login ghcr.io \
            -u ${{ github.actor }} --password-stdin
          spin registry push "$IMAGE"
      - name: Bump the image tag
        run: |
          yq -i ".spec.image = \"$IMAGE\"" deploy/hello/spinapp.yaml
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git commit -am "hello: ${GITHUB_SHA::7}"
          git push

Commits pushed with the workflow’s GITHUB_TOKEN don’t trigger new runs, so the tag bump can’t cause a build loop. The paths-ignore filter covers config-only commits you push yourself, like a rollback.

Because you pushed hello:v1 by hand, the workflow isn’t allowed to write to the package yet. In the package settings, under Manage Actions access, add your repository with the Write role.

ghcr.io Package Access

Now commit the workflow together with a change to the app, for example a new response text in src/index.ts:

# Commit & Push to GitHub
git add .
git commit -m "hello: new greeting"
git push

flux bootstrap configures Flux to check the repository every minute, so the rollout starts shortly after the workflow pushes its tag bump. Once it does, follow it with:

kubectl rollout status deployment/hello

Rolling Back With git revert

The image tag is just a line in Git, so a rollback is a revert of the commit that bumped it. App commits and tag bumps share one history, so look up the bump instead of reverting HEAD:

# Pull recent changes
git pull
git log --oneline -- deploy/hello/spinapp.yaml
git revert <sha-of-the-bump>
git push

Flux reconciles the previous SpinApp, and the operator rolls back to the previous image. You get the same audit trail and review process you already have for every other workload.

Recap

Keep your Spin app and its SpinApp manifest in one repository, point Flux at the manifest, let a GitHub Actions workflow bump the image tag, and use git revert to roll back. Flux treats a SpinApp like any other resource, so your Wasm apps follow the same GitOps flow as every other workload in the cluster. The only Wasm-specific part is the Spin shim on your nodes, which SpinKube takes care of.

Thorsten Hans
Thorsten Hans
Sr. Developer Advocate

Thorsten Hans is a Senior Developer Advocate at Akamai, Docker Captain, and Wasm enthusiast. He thrives on pushing the limits of WebAssembly and Edge Computing to help developers build high-performance distributed systems. Thorsten shares his technical deep-dives via his blog and on global stages to shape the cloud's future.