Flag helm annotations as an advanced feature

public/docs/img/argo-cd/update-application-image-tags-helm-values-tag.png.json

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

src/pages/docs/argo-cd/annotations/helm-annotations.md

@@ -1,13 +1,17 @@
 ---
 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
+navTitle: Helm Annotations (deprecated)
 hideInThisSectionHeader: true
 ---
 
+:::div{.warning}
+**Deprecated:** Helm image path configuration via Argo CD Application annotations is deprecated. You should configure Helm image paths directly in the [Update Argo CD Application Image Tags step](/docs/argo-cd/steps/update-application-image-tags) instead.
+:::
+
 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.
 

src/pages/docs/argo-cd/steps/update-application-image-tags.md

@@ -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.