Enable Automations with Helm

Automations run OpenHands conversations on a schedule or in response to an event. This guide adds the automation service to an existing Enterprise Helm installation. Complete Install with Helm and confirm that a regular conversation works before enabling automations. The shared configuration below uses bundled PostgreSQL. Choose automation package storage for your provider before applying it. For production, use external PostgreSQL and adapt the database host and credentials accordingly. The storage settings below apply to chart 0.88.0, which ships Automation 1.23.2. Keep the automation image supplied by your licensed chart unless your release instructions require an override. Compare these settings with your licensed chart values before installing or upgrading.

Prerequisites

A public HTTPS application origin, such as https://app.openhands.example.com. Event-based automations need a URL the event source can reach.
A PostgreSQL instance reachable from the automation pod. This example creates a separate automations database and automation_user in the bundled instance.
A durable S3-compatible or GCS bucket for automation packages, with access to list the bucket and read, write, and delete objects. Provision storage and permissions separately from the application values below.
Required and optional Kubernetes Secrets, with values stored in your secret manager:

Secret	Key	Purpose
`automation-db-secret`	`db-password`	Password for `automation_user`
`automation-service-key`	`automation-service-key`	Authenticates OpenHands requests to the automation service
`automation-webhook-secret`	`webhook-secret`	Verifies automation webhook signatures
`automation-filestore-credentials`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	Required when using S3-compatible access keys; omit for ambient AWS identity or GCS
`automation-git-sync-secret`	`git-sync-secret`	Optional: enables storing encrypted Git sync credentials
`automation-kv-secret`	`kv-secret`	Optional: enables persistent automation KV state

Choose Package Storage

Enterprise conversation storage (filestore) and automation package storage (automation.filestore) are separate consumers. Configuring one does not configure the other. Use a separate automation bucket, such as automation-data, even when both consumers use the same object-store endpoint. Workspace PVCs are separate again. The chart defaults to automation.filestore.type: gcs; explicitly set type: s3 when using S3 or RustFS.

Amazon EKS
Azure AKS
Google GKE

Use Amazon S3 with IRSA or EKS Pod Identity granted to the automation service account. IRSA is EKS-specific; do not copy its annotation into AKS or GKE values. For IRSA, merge this into the shared configuration below:

automation:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::<account-id>:role/<automation-s3-role>
  filestore:
    type: s3
    bucket: <automation-package-bucket>
    region: <aws-region>

Leave endpoint empty for AWS S3. Provision the bucket and IAM access first.

Use the chart’s optional RustFS dependency with persistent disks, or an external S3-compatible service. Native Azure Blob storage is not implemented for automation packages. Use S3-compatible credentials for RustFS or external S3 storage; Azure workload identity does not supply those access keys.

Follow AKS Object Storage and the RustFS provisioning example to configure Azure Disk CSI persistence and the store’s credential Secret. Create the conversation bucket separately if using RustFS for conversations.
Configure a separate automation-data bucket using the S3-compatible settings below. The existing AKS automation overlay shows the RustFS service endpoint and Secret reference.

That overlay pins Automation 1.15.1 for chart 0.74.0. Do not carry that image override into chart 0.88.0; use its bundled 1.23.2 image and compare the versioned chart values before adapting the overlay. Preserve the AKS runtime overrides by passing values-aks-runc.yaml last on every upgrade.

Choose GCS with Workload Identity Federation for GKE, or RustFS with Persistent Disk CSI as described in GKE Object Storage.For GCS, enable Workload Identity Federation on the cluster and the node pool running automation pods. Provision a separate automation bucket and grant access to the identity used by the automation pod’s Kubernetes service account (automation.serviceAccount.name, default automation-sa). Configure the GKE identity binding for that account in the release namespace (openhands in this guide), independently of the Enterprise application account. If using IAM service-account impersonation, set the required iam.gke.io/gcp-service-account annotation through automation.serviceAccount.annotations as described in Google’s guide.

automation:
  filestore:
    type: gcs
    bucket: <automation-package-bucket>

GCS uses Application Default Credentials from the pod’s ambient Google identity. S3 credential Secret references do not authenticate GCS. The LLM gateway’s Vertex credentials are also separate. Provision the GCS bucket first; createBucket applies only to S3.For RustFS, provision the store and disks using the GKE guide, then configure automation with the S3-compatible settings below.

S3-Compatible Settings for RustFS or External Storage

After provisioning the store, merge the following into your automation values. These are application connection settings; they do not deploy RustFS, provision its disks, or configure backup and restore.

automation:
  filestore:
    type: s3
    bucket: automation-data
    endpoint: http://<rustfs-service>:9000
    region: us-east-1
    createBucket: false
    existingSecret: automation-filestore-credentials
    accessKeyIdKey: AWS_ACCESS_KEY_ID
    secretAccessKeyKey: AWS_SECRET_ACCESS_KEY

Replace the endpoint with the reachable S3 API URL and use the region required by your store (us-east-1 in the AKS RustFS example). The URL scheme determines TLS; use the appropriate trusted HTTPS endpoint for an external service. The referenced Secret must be in the openhands release namespace and contain the two named keys. It can reference the same credential Secret as the store if its grants cover the separate automation bucket. If reusing a Secret with different key names, set accessKeyIdKey and secretAccessKeyKey to match. Never put real access keys in values or Git. Provision the bucket first, or set automation.filestore.createBucket: true and grant bucket-creation permission to let the automation service create it at startup. Enabling RustFS alone does not create or select the automation bucket. Plan disk capacity, availability, backups and restore for the in-cluster store.

For new installations, follow the Helm guide’s minio.enabled: false and use external storage or RustFS. Legacy MinIO images can fail to pull. Check custom values for MinIO overrides. Before replacing an existing store, plan backup and data migration.

Step 1: Create Secrets

Use independent, random values for the database password, service key and webhook secret. Create these three Kubernetes Secrets in the openhands namespace, plus the filestore credential Secret if using S3-compatible access keys. Create the optional Git sync and KV Secrets if you need those features; without them, Git sync credential storage is unavailable and the KV store is disabled. If you create Secrets with kubectl, use --from-file or your secret manager rather than putting values directly in a shell command. The service key and webhook secret should differ. Keep secret values out of your Helm values file and Git repository.

Step 2: Add Helm Values

Add the following to the values you already use for the openhands release. Replace the host and database settings with your own, and merge exactly one storage choice from above into this configuration. Keep your existing installation values alongside these overrides when upgrading. Remove automation.image.tag overrides copied from older versions of this guide or the AKS overlay, unless your release instructions explicitly require an override.

automationServiceKey:
  enabled: true

automationWebhookSecret:
  enabled: true

automationService:
  url: https://app.openhands.example.com/api/automation
  eventForwardingEnabled: true

automation:
  enabled: true
  openhandsApiUrl: https://app.openhands.example.com
  automationBaseUrl: https://app.openhands.example.com
  database:
    host: openhands-postgresql.openhands.svc.cluster.local
    port: "5432"
    user: automation_user
    name: automations
    secretName: automation-db-secret
    secretKey: db-password
    createDatabaseUser: true
    superuserName: postgres
    superuserSecretName: postgres-password
    superuserSecretKey: password
  serviceKeyFromSecret:
    name: automation-service-key
    key: automation-service-key
  automationWebhookSecretFromSecret:
    name: automation-webhook-secret
    key: webhook-secret

automation.automationBaseUrl is the public origin, without /api/automation. The automation service mounts its API under this value’s path plus /api/automation. Including the path here doubles the API prefix, so Canvas receives a 404 from /api/automation/health and reports “Automations Unavailable” even though the automation pod is Ready.

The automationService.url value does include /api/automation. It is used by the OpenHands application to reach the automation service.

automationService.eventForwardingEnabled is what makes the built-in event sources deliver: GitHub, Azure DevOps, Jira Data Center, and Bitbucket Data Center events reach automations only when it is true (Replicated installations set it when Automations are enabled). Jira Data Center events also need jiraDc.enabled: true, which turns on its webhook endpoint. See Data Center Event Automations.

Step 3: Upgrade and Verify

Upgrade the same licensed release used for your initial installation. This example assumes the baseline and merged automation values are in separate files. Use your installed chart version; enabling storage is not a release upgrade. On AKS, append --values values-aks-runc.yaml last:

helm upgrade openhands oci://registry.replicated.com/openhands/openhands \
  --namespace openhands \
  --version <installed-chart-version> \
  --values values.yaml \
  --values values-automation.yaml

kubectl -n openhands rollout status deployment/automation
kubectl -n openhands get deployment automation \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
# Chart 0.88.0: ghcr.io/openhands/automation:1.23.2
curl -f https://app.openhands.example.com/api/automation/health

On AKS, the upgrade command is:

helm upgrade openhands oci://registry.replicated.com/openhands/openhands \
  --namespace openhands \
  --version <installed-chart-version> \
  --values values.yaml \
  --values values-automation.yaml \
  --values values-aks-runc.yaml

Before running an automation, check that the selected bucket exists, the pod uses the intended service account, and its storage Secret references or workload identity grants match the bucket. Check pod events and logs for image-pull, credential, endpoint or bucket-access errors without printing Secret contents. A successful health response alone does not verify package storage. Sign in to OpenHands and open Automate in Canvas. Create a read-only prompt automation, run it once with Run now, and confirm that a completed run appears in Activity Log. For example, ask it to summarize the README of a test repository without changing files or posting messages. Disable the test schedule afterward if you do not want it to run again. Check the automation bucket for the package object after the test run, using an object-store client authenticated with your approved storage identity:

# Amazon S3
aws s3 ls s3://<automation-package-bucket>/ --recursive

# GCS
gcloud storage ls --recursive gs://<automation-package-bucket>/

# External S3-compatible service, or RustFS from a client inside the cluster
aws --endpoint-url <s3-api-url> s3 ls s3://<automation-package-bucket>/ --recursive

An in-cluster RustFS service name is reachable only inside the cluster. Run its listing command from a client pod, or port-forward svc/<rustfs-service> with kubectl -n openhands port-forward svc/<rustfs-service> 9000:9000 and use --endpoint-url http://localhost:9000 from your workstation. In a test environment, restart the automation deployment:

kubectl -n openhands rollout restart deployment/automation
kubectl -n openhands rollout status deployment/automation

Run the same automation again with Run now and confirm it completes. This checks that package storage survives pod replacement. A healthy pod alone does not verify storage access or persistence.

Troubleshooting Storage

Symptom	Check
S3 connection or TLS error	The S3 API endpoint is reachable from the automation pod, uses the correct port and URL scheme, and has a trusted certificate when using HTTPS.
S3 access denied or missing bucket	The Secret name and key names match, the bucket exists, and credentials grant access to the automation bucket. Bucket auto-creation also requires creation permission.
Unexpected GCS or ADC error on AKS/EKS	Confirm `automation.filestore.type: s3` is set when using S3-compatible storage.
GCS authentication or permission error	Workload Identity is enabled on the automation node pool, the pod uses the intended Kubernetes service account, and that identity has access to the automation bucket.
Healthy pod but package cannot be read	Check `automation.filestore`, not just the application’s top-level `filestore`, and verify the package object is in the selected automation bucket.

For creating and managing automations, see Automations Overview. For events from another service, see Event-Based Automations.

Get Started

Deployment

Configuration

Integrations

Features

Administration

Enable Automations with Helm

Prerequisites

Choose Package Storage

S3-Compatible Settings for RustFS or External Storage

Step 1: Create Secrets

Step 2: Add Helm Values

Step 3: Upgrade and Verify

Troubleshooting Storage