The Update Argo CD Application Image Tags step is responsible for iterating over your Argo CD Application’s repository, and updating the image tag for referenced container images.
When deploying a Helm Chart with multiple values files, specific annotations must be added to your Argo CD Application to ensure the correct sections of the relevant values files are updated. See Helm Annotations for more information.
Container Images
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.
If the application cluster’s default registry has been changed, see cluster annotations to ensure the correct default registry is shared with Octopus.
These packages can then be used in an external feed trigger, such that your cluster is automatically updated when new image versions become available.
Creating and Deploying a Release
The step will fail to execute if no git credentials exist for repositories referenced by your Argo CD Applications. As such, prior to execution, it is recommended to use the Argo CD Applications View to ensure no outstanding configuration is required.
When a release of the project is created, a snapshot of the versions of container images referenced in the step is taken.
For each application with relevant scoping annotations found during a deployment, Octopus will checkout each repository using git credentials determined based on repository restrictions.
How Octopus updates image tags varies for each source type
For Kubernetes YAML:
- Octopus searches for Kubernetes resources which are known to reference images (CRDs are not included)
- If a resource references an image configured as a referenced container image, the image tag is updated to match that in the release
For Helm charts:
- Image fields are extracted from the Helm Annotations
- Matching image tags in the
values.yamlare replaced with container image versions from the release
For Kustomize applications (i.e. supplied path contains kustomization.yaml, kustomization.yml or Kustomization):
- Octopus will only update the
newTagfield(s) found in the Kustomize file. No other files will be edited.
Finally, changed files are committed and pushed back to the repo/branch specified by the Argo CD Application
A PR will be created (rather than merging to the targetRevision branch) if configured in the step UI.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Wednesday, March 11, 2026