GitHub Action

Deploy on every push, from your own CI, to your own cluster.

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci

      - uses: docker/login-action@v3
        with:
          registry: registry.example.com
          username: ${{ secrets.REGISTRY_USER }}
          password: ${{ secrets.REGISTRY_TOKEN }}

      - uses: getknext-dev/knext/packages/kn-next-action@v1
        with:
          kubeconfig: ${{ secrets.KUBECONFIG_B64 }}
          namespace: acme
          registry: registry.example.com/acme
          registry-token: ${{ secrets.REGISTRY_TOKEN }}
          skip-upload: 'true'

That is the whole thing. Push to main, and ACME redeploys.

You don't need a Bun setup step of your own: this action installs the Bun toolchain it needs to compile your app before it deploys, even on a stock ubuntu-latest runner. Everything else — the Node.js and Docker steps above — is what your own build needs, not what the action needs.

What this action deliberately does not do

It never asks for cloud-account credentials, and it does not create clusters.

That is a design decision, not an omission. Creating managed Kubernetes requires permissions that cannot be scoped down. On AWS, eksctl's own documented minimum grants iam:CreateRole + iam:AttachRolePolicy + iam:PassRole — which together are the textbook privilege-escalation primitive, with no conditions attached to stop it. A credential that can create a cluster can generally do anything in the account, and the bill arrives either way.

A kubeconfig is different in kind. It is scoped to one cluster, and can be scoped further to one namespace. Leaked, it costs you that cluster — not your cloud account.

So: you bring a cluster, this action does everything after it.

Two shapes, and which to pick

Credential-free — skip-upload: 'true'

Needs only a kubeconfig and registry auth. Nothing cloud-specific.

You lose static-asset offload to object storage and the post-deploy asset GC. The app still builds, deploys, serves and scales to zero. Start here — it is the shortest path to a working pipeline, and you can add uploads later without changing anything else.

Full parity — assets uploaded

knext shells out to your storage provider's CLI, so authenticate it before the deploy step, using whichever action your provider already publishes:

      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.GCP_SA }}

      - uses: getknext-dev/knext/packages/kn-next-action@v1
        with:
          kubeconfig: ${{ secrets.KUBECONFIG_B64 }}
          namespace: acme
          registry: registry.example.com/acme
          registry-token: ${{ secrets.REGISTRY_TOKEN }}
          bucket: acme-assets

The equivalents are aws-actions/configure-aws-credentials, azure/login, or mc alias set for MinIO. In every case the action authenticates to a bucket you already own — it never creates one.

Getting the kubeconfig

Do not use your personal admin kubeconfig. The action refuses one — see below — so the fastest path is also the correct one:

knext init-ci --namespace my-app

That writes two files and touches nothing in your cluster:

• .github/workflows/knext-deploy.yml — the workflow, with every secret it needs documented at the top
• knext-ci-rbac.yaml — a ServiceAccount, a Role and a RoleBinding

Read the manifest, then apply it yourself:

kubectl apply -f knext-ci-rbac.yaml

Build a kubeconfig from the knext-deployer ServiceAccount's token. A token Secret gives CI a credential that does not expire the way kubectl create token output does. The manifest holds no token; Kubernetes fills it in:

kubectl apply -f - <<'YAML'
apiVersion: v1
kind: Secret
metadata:
  name: knext-deployer-token
  namespace: my-app
  annotations:
    kubernetes.io/service-account.name: knext-deployer
type: kubernetes.io/service-account-token
YAML

umask 077
SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
CA=$(kubectl -n my-app get secret knext-deployer-token -o jsonpath='{.data.ca\.crt}')
TOKEN=$(kubectl -n my-app get secret knext-deployer-token -o jsonpath='{.data.token}' | base64 -d)
cat > ci-kubeconfig.yaml <<YAML
apiVersion: v1
kind: Config
clusters: [{name: cluster, cluster: {server: $SERVER, certificate-authority-data: $CA}}]
users: [{name: knext-deployer, user: {token: $TOKEN}}]
contexts: [{name: ci, context: {cluster: cluster, user: knext-deployer, namespace: my-app}}]
current-context: ci
YAML

Check that it is the scoped one: KUBECONFIG=ci-kubeconfig.yaml kubectl auth can-i get secrets -n my-app must answer no. Then base64-encode it, store it as an encrypted secret under Settings → Secrets and variables → Actions, and delete the file:

base64 -w0 < ci-kubeconfig.yaml    # macOS: base64 -i ci-kubeconfig.yaml
rm ci-kubeconfig.yaml

Store it on an environment limited to your default branch, not as a repository secret. Then a pull request that edits the workflow still cannot read it.

The action loads its credential check from your app's installed @getknext/core, so install your dependencies (npm ci) in a step before it.

What the credential can actually do

This is the whole Role. There is no second page:

rules:
  - apiGroups:
      - apps.kn-next.dev
    resources:
      - nextapps
    verbs:
      - get
      - list
      - create
      - patch
      - update

No delete, so a leaked token cannot remove your app. No secrets, so it cannot read your database password. No Deployments, Services or Pods at all.

That is possible because deploying is writing one object. The operator running in your cluster watches for it and does everything else — Knative configuration, autoscaling, networking. CI never needs to touch any of it.

Inputs

The action sets no outputs. The deployed URL is reported by the cluster — read it with kubectl get ksvc -n <namespace>, or knext status. An output that was empty on every dry run and unreliable otherwise would be worse than none.

Preview deploys on pull requests

dry-run prints the NextApp custom resource that would be applied, without touching the cluster:

on: pull_request

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - uses: getknext-dev/knext/packages/kn-next-action@v1
        with:
          kubeconfig: ${{ secrets.KUBECONFIG_B64 }}
          namespace: acme
          registry: registry.example.com/acme
          dry-run: 'true'

This makes the diff reviewable before it lands — the same instinct as terraform plan.

Passing values from pull requests

Every input reaches the action's scripts as an environment variable, never pasted into script text, so a value like a branch name cannot run as a command. tag and bucket are also checked against the shapes listed above and refused if they do not fit, with an error that names the rule and does not repeat the value. Your own workflow is still yours to protect: prefer github.sha for the tag, and do not build the input from text an outside contributor controls without checking it first.

Why doctor runs first

By default the action runs the read-only knext doctor preflight and fails the job if the cluster is not ready. It checks that the CRD exists, the operator is Ready, Knative Serving is installed, and the ingress class matches the controller actually serving traffic.

These failures are much cheaper to read here than halfway through a container build. Set doctor: 'false' to skip it, though there is rarely a good reason to.

Related

• Tutorial: deploy ACME — the manual path this automates
• CLI reference — every verb and flag the action wraps
• Upgrading — why the operator is upgraded before the CLI