Flag helm annotations as an advanced feature (#3060)

Author: rain-on

public/docs/i/1000/argo-cd/update-application-image-tags-helm-values-tag.webp

@@ -0,0 +1 @@
+{"width":1588,"height":1214,"updated":"2026-03-11T00:40:11.726Z"}

public/docs/i/2000/argo-cd/update-application-image-tags-helm-values-tag.webp

@@ -1,15 +1,19 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2025-09-15
-modDate: 2025-09-15
+modDate: 2026-03-11
 title: Helm Image Tags Annotations
 description: What annotations are required to
 navTitle: Helm Annotations
 hideInThisSectionHeader: true
 ---
 
+:::div{.info}
+**Advanced Feature:** Helm image path configuration via Argo CD Application annotations is an advanced feature, and should only be used if configuring Helm image paths directly in the [Update Argo CD Application Image Tags step](/docs/argo-cd/steps/update-application-image-tags) is insufficient for your requirements.
+:::
+
 When executing the [Update Argo CD Application Image Tags step](/docs/argo-cd/steps#update-application-image-tags) against an Argo CD Application that is deploying a Helm chart,
-it is necessary to provide extra annotations to define which fields in the Helm values file represent an image to be updated.
+it is necessary to provide extra information to allow Octopus to identify the appropriate fields in the Helm values file to update.
 
 This is because an image reference could be made up of multiple different values file entries. Consider the image fields in [values.yaml](https://github.com/OctopusDeploy/helm-charts/blob/main/charts/kubernetes-agent/values.yaml) for the Kubernetes agent Helm chart:
 
@@ -37,7 +41,12 @@ global:
 
 In this case, the `global.image.repositoryAndTag` contains the tag to be updated.
 
-As the structure of Helm values files can vary widely between charts, it's necessary to require you to specify custom annotations on the Argo CD Applications.
+Typically the value path to update would be provided via the **helm image value** field on the package/container defined during step configuration. However, for more complex use cases, you can define the fields to update via custom annotations.
+
+:::div{.info}
+Annotations will only be considered during step-execution if *none* of the packages/containers defined for a step have a helm image value configured.
+Thus, if any package/container in your step requires annotations, then all packages must be updated using annotations.
+:::
 
 The annotation is as follows:
 

public/docs/i/600/argo-cd/update-application-image-tags-helm-values-tag.webp

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2025-09-15
-modDate: 2026-03-04
+modDate: 2026-03-11
 title: Update Argo CD Application Image Tags
 description: Deployment steps to modify your Argo CD Applications
 navOrder: 30
@@ -20,6 +20,12 @@ more information.
 
 Add package references for each container image you would like to update when you run your deployment. Unreferenced container images in your manifests will not be changed by Octopus.
 
+When targeting a Helm-based application source, each referenced container image should have a populated **Helm image tag path** field. This is the YAML path to the specific field in your values file that contains the tag of the referenced container image (for example, `agent.image.tag`). This can be set in the **Reference a package** drawer when adding or editing a package reference. This is not required for directory or Kustomize sources.
+
+:::figure
+![The Helm image tag path field in the Reference a package drawer](/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png)
+:::
+
 If the application cluster's default registry has been changed, see [cluster annotations](/docs/argo-cd/annotations/cluster-annotations) to ensure
 the correct default registry is shared with Octopus.