title: 'CI/CD Deployment' sidebar_label: 'CI/CD' sidebar_position: 7 description: 'Deploy Spice.ai applications using continuous integration and delivery pipelines, including Helm, Kubernetes GitOps with Argo CD or Flux, GitHub Actions, and the Spice Cloud deploy action.' keywords: [ spice.ai, deployment, ci/cd, cicd, helm, kubernetes, github actions, gitops, argo cd, flux, spicepod, spice cloud, ] tags:
Spice deployments can be automated through continuous integration and delivery (CI/CD) pipelines. The recommended approach for self-hosted, open-source deployments is the Spice Helm chart, driven either directly from a pipeline runner or declaratively through a GitOps controller. Container and cloud-VM workflows are also supported, as is a managed deploy action for the Spice Cloud Platform.
The sections below cover, in order:
spicehq/spice-cloud-deploy-action GitHub Action.:::tip Self-hosted enterprise deployments
For production self-hosted deployments, the Spice.ai Enterprise Kubernetes Operator is the recommended approach. The operator provides per-replica StatefulSets, automatic PVC resizing, configurable update strategies, crashloop protection, and distributed query execution through SpicepodSet and SpicepodCluster custom resources, all reconcilable from Git through the same GitOps tooling described below.
:::
The Spice Helm chart is the primary deployment artifact for self-hosted clusters. Any CI runner with kubectl and helm installed can roll out a release by checking out the repository, authenticating to the target cluster, and running helm upgrade --install.
The chart loads the Spicepod from a spicepod key in the values file. A typical layout keeps a single values.yaml that contains both chart configuration and the Spicepod definition:
For details on chart values, see the Helm deployment guide.
The workflow below deploys the chart to a Kubernetes cluster on every push to main. Cluster credentials are provided through a base64-encoded kubeconfig stored in the KUBE_CONFIG repository secret.
--atomic rolls back on failure, and --wait blocks until the release is healthy, so a failed deploy fails the pipeline.
The same pattern works in GitLab CI. The job uses the official alpine/helm image and reads cluster credentials from a CI/CD variable.
Production pipelines should pin both the chart and the Spice runtime image to specific versions. Pass --version to helm upgrade to pin the chart, and set image.tag in values.yaml to pin the runtime image:
Available chart versions are listed in the helm-charts repository. Runtime image tags are published on GitHub Container Registry.
To promote the same artifact across environments, keep a base values.yaml and add per-environment overlays such as values.staging.yaml and values.prod.yaml. Helm merges multiple -f flags in order:
Each environment can target a different cluster, namespace, or image tag while sharing the same Spicepod definition.
GitOps controllers reconcile cluster state from a Git repository, removing the need for the pipeline to hold cluster credentials. The controller runs inside the cluster and pulls changes as they are committed.
Application manifests reconciled by the Argo CD controller.HelmRelease resources reconciled by the Flux toolkit.Both guides include end-to-end manifests targeting the official chart, including upgrade and rollback patterns. GitOps is the recommended approach for multi-cluster or multi-environment deployments.
For deployments that target a container runtime or a cloud VM rather than Kubernetes, invoke the standard provider tooling from any pipeline runner:
spiceai/spiceai image. Pipelines typically run docker build and docker push against a registry, then docker compose up -d or docker run on the target host.Each provider guide includes the deployment artifact (image, template, or script) that the pipeline invokes.
Deployments targeting the Spice Cloud Platform can be automated two ways:
spicehq/spice-cloud-deploy-action to deploy from a custom workflow. Use this when the pipeline needs to run tests, build artifacts, or set secrets and tags before deploying.The spicehq/spice-cloud-deploy-action deploys a Spicepod manifest to a Spice Cloud app on each pipeline run.
SPICE_CLIENT_ID and SPICE_CLIENT_SECRET — store its credentials.spicepod.yaml checked into the repository.| Input | Purpose |
|---|---|
app-name or app-id | Target Spice Cloud app. One is required. |
spicepod | Path to the Spicepod manifest. Defaults to spicepod.yaml. |
region | Required when create-app-if-missing provisions a new app (for example, us-east-1). |
create-app-if-missing | Boolean. Creates the app on first deploy. |
secrets | YAML or JSON map of app-level secrets to set on the deployment. |
tags | YAML or JSON map of metadata labels. |
test-sql, test-chat, test-search | Post-deploy smoke checks against the deployed app. |
wait-for-completion | Poll until the deployment finishes. Defaults to true. |
The action emits app-id, app-url, deployment-id, deployment-status, and test-results outputs that downstream steps can consume. For the full input and output reference, see the action's README.
timeout-seconds | Maximum time to wait when polling. Defaults to 600. |