The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
For a list of other such plugins, see the Pipeline Steps Reference page.
rancherHelm: Rancher Helm DeploymentInstall or upgrade a Helm chart through Rancher Manager catalog API on the controller. Requires a configured System connection or Manual URL + API token on this step.
Set Project (Rancher project name or p-xxxxx) and Namespace. Catalog install/upgrade uses that project. After catalog HTTP 201 the step polls the Helm operation from chartActionOutput, then the Helm app until this operation has settled and helm-owned workloads are active, logging Helm operation and app state and object changes from relationships. Ready app with a workload that is not active fails the build. Failed Helm never succeeds, even if workloads still look active; a failed operation includes the Helm job log tail (Recent Operations → Logs). The chart repository URL (http(s):// or oci://) is mapped to an existing ClusterRepo. If catalog cannot find the chart, that index is refreshed and catalog is retried once. Use Validate only to dry-run without project lookup, ClusterRepo refresh, namespace create, install, upgrade, uninstall, or wait.
clusterId : String
Rancher cluster id (for example local or c-m-xxxx). The plugin uses it in GET /v3/clusters/{id}, manifest apply, and Helm catalog calls.
In Rancher Manager: open the cluster, then check the browser URL (…/dashboard/c/<cluster-id>/…) or Cluster → Details (id field). For the local cluster, the id is often local.
releaseName : String
Helm release name in the target namespace (DNS-1123).
chart : String
Chart name within the repository (for example nginx).
repo : String
Chart repository URL that matches an existing Rancher ClusterRepo spec.url.
Supported schemes:
https://charts.example/helm — classic Helm index repositoryhttp://charts.example/helm — same (HTTP)oci://registry.example/charts — OCI chart registry (Rancher Manager 2.9+)If catalog cannot find the chart version, the step refreshes that ClusterRepo like the Rancher UI (sets spec.forceUpdate and waits) and retries once. The ClusterRepo must already exist in Rancher; the step does not create it. Registry credentials for private OCI hosts belong on the ClusterRepo in Rancher, not on this step.
atomic : boolean (optional)
On failed upgrade, roll back changes (Helm --atomic).
cleanupOnFail : boolean (optional)
Allow deletion of new resources created in this upgrade when the upgrade fails (Helm --cleanup-on-fail).
ensureNamespace : boolean (optional)
When enabled, create the namespace in the selected Project if it does not exist (project annotation and label on the Namespace). The step does not create ResourceQuota or LimitRange.
When disabled, the namespace must already exist in that project. Existing namespaces are never moved or patched. Skipped when Validate only is checked.
forceReinstall : boolean (optional)
When checked, uninstall the release (if present) then install.
Destructive — prefer the default install-or-upgrade path unless you need a clean reinstall.
helmTimeoutSeconds : String (optional)
Time to wait for any individual Kubernetes operation; default in Helm is 5m0s (Helm --timeout).
helmWait : boolean (optional)
Wait until Pods/PVCs/Services and min ready replicas of Deployment/StatefulSet/ReplicaSet are ready before success (Helm --wait).
namespace : String (optional)
Target Kubernetes namespace (Helm --namespace). Default default.
The namespace must belong to the Project field. When Ensure namespace is enabled and the namespace is missing, the plugin creates it in that project. An existing namespace in a different project (or in none) fails the build; the step does not move namespaces.
project : String (optional)
Rancher project name as shown in the UI (for example Default), or the project id (p-xxxxx). The plugin lists projects with GET /v3/clusters/{clusterId}/projects for this step’s Cluster ID.
Do not put the cluster id here (not local:p-xxxxx). Cluster belongs in Cluster ID.
rancherConnectionMode : String (optional)
Inherit from System: This setting is made in the System tab of Manage Jenkins (Rancher Manager).
Manual: set Rancher URL and Secret text API token on this step.
rancherCredentialsId : String (optional)
Secret text with the Rancher Bearer Token (token-…:… from Account API Keys), not Access Key alone.
rancherUrl : String (optional)
Rancher Manager base URL (e.g. https://rancher.example).
validateOnly : boolean (optional)
Preflight and field validation only.
values : String (optional)
Inline Helm values YAML when Values source is Manual YAML. Must be a mapping (key: value). Build logs do not include the YAML body.
Use Values overlay for a last merge layer (for example image tags) on top of this YAML or another Values source.
valuesFilePath : String (optional)
Path to the values file relative to the repository root. Default values.yaml.
valuesGitCredentialsId : String (optional)
Optional Username with password or Secret text for private Git repositories used to fetch the values file. Secret text is used as a token with username oauth2 (common for GitLab/GitHub PAT).
valuesOverlay : String (optional)
Patch chart values at deploy time without editing the base file — typically image tags. Merged last over Values source; leave blank if unused. Never written to the build log.
Example:
backend:
image:
tag: "${BUILD_TAG}"
valuesRepositoryReferenceName : String (optional)
Git reference for the values repository. Default: refs/heads/main.
Examples:
refs/heads/mainrefs/tags/v1.2.0refs/heads/${BRANCH_NAME}valuesRepositoryUrl : String (optional)
Git repository URL hosting the values file (not the chart repo).
Do not put credentials in the URL (no user:pass@host). Use Git credentials for private repos.
On GitLab, project visibility Public does not always allow git clone: if Settings → Visibility → Repository (download code) is off, clone fails with a download-disabled error — that is not a missing Jenkins git credential.
Example: https://gitlab.example/group/helm-values.git
valuesSource : String (optional)
Where base Helm chart values come from: none (chart defaults), a Git repository file, or inline YAML. Sent to Rancher catalog install/upgrade as JSON (never logged).
Optional Values overlay is a separate last merge layer on top of this source — not a fourth Values source.
verboseLogging : boolean (optional)
When enabled, debug-level logs for HTTP requests will be duplicated in the build console.
version : String (optional)
Optional chart version. Empty uses the repository default or latest resolved by Rancher.
waitTimeoutSeconds : String (optional)
How long this job waits for the Helm release to become ready after catalog. Default 300 seconds. Leave blank for the default.
rancherManifest: Rancher Manifest DeploymentApply Kubernetes YAML to a cluster through Rancher Manager (Steve action=apply), then wait until Deployment, StatefulSet, DaemonSet, and Job from that YAML are ready (same idea as Helm wait). Requires System connection or Manual URL + API token on this step. Namespace comes from the manifest, not from this step.
Use Validate only to dry-run without apply or wait.
clusterId : String
Rancher cluster id (for example local or c-m-xxxx). The plugin uses it in GET /v3/clusters/{id}, manifest apply, and Helm catalog calls.
In Rancher Manager: open the cluster, then check the browser URL (…/dashboard/c/<cluster-id>/…) or Cluster → Details (id field). For the local cluster, the id is often local.
gitCredentialsId : String (optional)
Optional Username with password or Secret text for private Git repositories used to fetch the manifest file. Secret text is used as a token with username oauth2 (common for GitLab/GitHub PAT).
manifestFilePath : String (optional)
Path to the manifest YAML inside the repository (relative; default manifest.yaml).
manifestSource : String (optional)
Repository: Jenkins fetches YAML from Git and applies it via Rancher (Steve action=apply).
Manual YAML: paste manifest content in the job configuration.
Example repository: https://gitlab.example/group/manifests.git
manifestYaml : String (optional)
Inline Kubernetes YAML when Manifest source is Manual YAML. Applied via Rancher Steve action=apply. Namespace comes from the YAML. Build logs do not include the YAML body.
rancherConnectionMode : String (optional)
Inherit from System: This setting is made in the System tab of Manage Jenkins (Rancher Manager).
Manual: set Rancher URL and Secret text API token on this step.
rancherCredentialsId : String (optional)
Secret text with the Rancher Bearer Token (token-…:… from Account API Keys), not Access Key alone.
rancherUrl : String (optional)
Rancher Manager base URL (e.g. https://rancher.example).
repositoryReferenceName : String (optional)
Git reference for the manifest repository. Default: refs/heads/main.
Examples:
refs/heads/mainrefs/tags/v1.2.0refs/heads/${BRANCH_NAME}repositoryUrl : String (optional)
Git repository URL hosting the manifest file.
Do not put credentials in the URL (no user:pass@host). Use Git credentials for private repos.
On GitLab, project visibility Public does not always allow git clone: if Settings → Visibility → Repository (download code) is off, clone fails with a download-disabled error — that is not a missing Jenkins git credential.
Example: https://gitlab.example/group/manifests.git
validateOnly : boolean (optional)
Resolve connection and validate manifest source without calling Rancher apply or namespace create.
verboseLogging : boolean (optional)
When enabled, debug-level logs for HTTP requests will be duplicated in the build console.
waitTimeoutSeconds : String (optional)
How long this job waits after apply for workloads to become ready. Default 300 seconds. Leave blank for the default.
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.