Helm Service
Deploy Services with local, OCI, or public Helm charts.
The helm Service type deploys applications with Helm charts. It supports
local charts, OCI registries, and public Helm repositories. You can include an
optional Docker build step for custom images.
Native Helm includes environment variable mapping and advanced deployment features.
See Native Helm deployment for more information.
Examples
Local chart with Docker build:
Chart configuration
The chart section is required and defines which Helm chart to deploy. Set the
chart fields in the Service configuration.
chart.name (required)
The chart name can be one of:
| Value | Description |
|---|---|
"./" or "../" prefix | Relative path to local chart |
"oci://..." | OCI registry chart URL |
| Chart name | Public chart name from a repository |
chart.repoUrl
URL of the Helm repository. This field is necessary for public charts.
chart.version
Specified chart version to deploy.
chart.values
Array of Helm values in key=value format.
chart.valueFiles
Array of value file paths relative to the repository root.
Docker configuration
The optional docker section defines how to build a custom image. Its
configuration matches the GitHub Service Docker
section.
docker.defaultTag
The default Docker image tag, typically matching the branch name.
docker.builder
Configuration for the Docker build operation. See GitHub Service
docker.builder for the full field list. That
section includes the resources field and the safe-to-evict pod annotation.
| Field | Type | Description |
|---|---|---|
engine | string | Build engine: buildkit, kaniko, or ci |
resources.requests | object | Minimum CPU/memory guaranteed for the build job |
resources.limits | object | Maximum CPU/memory allowed for the build job |
podAnnotations | Record<string,string> | Custom annotations applied to the build pod template |
docker.app (required with docker)
Configuration for the main application container:
dockerfilePath- Required. Path to Dockerfile relative to repo rootcommand- Override container entrypointarguments- Arguments passed to the command. Use%%SPLIT%%to delimit spaces, for example,-c%%SPLIT%%npm run start.env- Environment variablesports- Exposed container ports
docker.init (optional)
Configuration for an init container that runs before the main application. The
init container has the fields from docker.app.
Field reference
| Field | Type | Required | Description |
|---|---|---|---|
chart.name | string | Yes | Chart name or path |
chart.repoUrl | string | For public | Helm repository URL |
chart.version | string | No | Chart version |
chart.values | array | No | Inline Helm values |
chart.valueFiles | array | No | Value file paths |
repository | string | For builds | GitHub repository |
branchName | string | For builds | Branch to build from |
docker | object | No | Docker build config |
args | string | No | More Helm arguments |
version | string | No | Helm CLI version |
deploymentMethod | string | No | "native" or "ci" |
envLens | boolean | No | Enable the Environment Lens ingress banner |
grpc | boolean | No | Enable gRPC behavior for the Helm Service |
disableIngressHost | boolean | No | Disable Lifecycle’s generated ingress host |
overrideDefaultIpWhitelist | boolean | No | Let the Service configuration replace the default IP whitelist |
Native Helm configuration
When deploymentMethod: "native" is enabled, configure more native Helm Job
settings with the nativeHelm block.
| Field | Type | Required | Description |
|---|---|---|---|
nativeHelm.enabled | boolean | No | When no deploymentMethod override exists, enable native Helm |
nativeHelm.defaultHelmVersion | string | No | Helm version used by the runner |
nativeHelm.jobTimeout | number | No | Native Helm Job timeout |
nativeHelm.serviceAccount | string | No | Kubernetes ServiceAccount for the Job |
nativeHelm.defaultArgs | string | No | Default Helm arguments |
nativeHelm.image | string | No | Custom native Helm runner image |
nativeHelm.postRenderer.enabled | boolean | No | Enables or disables an inherited post-renderer |
nativeHelm.postRenderer.command | string | No | Executable passed to Helm with --post-renderer |
nativeHelm.postRenderer.args | array | No | Helm receives one --post-renderer-args flag for each argument |
Templated variables
Write Lifecycle template variables with triple braces. See the Template variables for the full list.
Triple braces {{{variable}}} distinguish a Lifecycle variable from a Helm
template function.
Native Helm deployment
To control Helm deployments, enable native Helm:
Native Helm runs the deployment as a Kubernetes Job. It streams deployment logs and accepts Helm arguments.
See Native Helm deployment for more information.