> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/use-gitops/gitops-entities/agents/argocd-3-upgrade.md).

# ArgoCD 3.1.8 upgrade

Learn what changed in the ArgoCD 3.1.8 upgrade included with Harness GitOps Agent 0.106.0

Harness GitOps Agent version 0.106.0 includes ArgoCD 3.1.8, a major version upgrade from the previous 2.x releases. This topic covers what changed, what improved, and what to review before you adopt this version.

***

## What you will learn from this topic

* How to review [what is included](#what-is-included) in GitOps Agent 0.106.0 and the bundled component versions
* How to evaluate the [key improvements](#key-improvements-in-argocd-318) in security, tooling, and performance
* How to plan for [breaking changes and deprecations](#breaking-changes-and-deprecations) that can affect custom integrations
* How to assess [Harness user impact](#how-this-affects-harness-users) and next resources

***

## Before you begin

Review the following before you plan an ArgoCD 3.x upgrade on a Harness GitOps Agent:

* **GitOps Agent familiarity**: Know how your account installs and upgrades the Harness GitOps Agent. Go to [GitOps Agent installation](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md) to review install and upgrade options.
* **Compatibility matrix**: Confirm which Agent versions support which ArgoCD releases. Go to [GitOps Agent version compatibility](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md#what-version-of-gitops-agent-supports-what-version-of-repo-server-and-redis-cache) to review the matrix.

***

## What is included

The following component versions are included in GitOps Agent 0.106.0:

* **ArgoCD version**: 3.1.8
* **Helm chart version**: 9.0.0 (from 7.x)
* **Bundled Helm version**: 3.18.4
* **Bundled Kustomize version**: 5.7.0
* **Redis version**: 7.4.1-alpine
* **HAProxy version**: 2.9.4-alpine

***

## Key improvements in ArgoCD 3.1.8

### Security enhancements

Version 3.1.8 includes security improvements that harden common attack paths in containerized environments.

The API server's `--staticassets` directory includes protection against out-of-bounds symlinks, which reduces the risk of exposing sensitive files outside the intended directory.

Project API responses are sanitized to address CVE GHSA-786q-9hcg-v9ff. The sanitization limits which configuration details appear in API responses.

OpenID Connect authentication uses the authorization code flow with PKCE on the server side rather than in the browser. This reduces the client-side attack surface and improves reliability in environments with strict content security policies.

### Tool upgrades

Helm and Kustomize are updated in this release. Helm 3.18.4 includes security patches and improved compatibility with recent Kubernetes versions. Kustomize 5.7.0 improves manifest generation performance and handling of complex overlays and patches, which matters for large multi-environment deployments.

***

## Breaking changes and deprecations

### API endpoint deprecation

The `/api/v1/applications/{name}/resource/actions` endpoint is deprecated. If you call this endpoint from custom scripts, Continuous Integration or Continuous Delivery pipelines, or integration code, migrate to the v2 endpoint at `/api/v1/applications/{name}/resource/actions/v2`.

The v1 endpoint remains available for backward compatibility. Inventory your callers and migrate them to the v2 endpoint.

### Helm chart upgrade

The jump from Helm chart version 7.x to 9.0.0 is a major version change and can introduce configuration differences. Some values in your `values.yaml` file might need updates. Go to [argo-cd Helm chart releases](https://github.com/argoproj/argo-helm/releases) to review changes that affect your setup before you upgrade production environments.

***

## Upgrade path

Moving from ArgoCD 2.x to 3.x is a major version upgrade with changes that touch security, APIs, and core functionality. ArgoCD maintainers document the migration in two parts.

Go to [upgrading from v2.14 to v3.0](https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/2.14-3.0/) to review the major breaking changes and architectural shifts. Go to [upgrading from v3.0 to v3.1](https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/3.0-3.1/) to review the incremental refinements in the 3.1 release. If you are coming from 2.x, read both guides.

{% hint style="info" %}
**ArgoCD 2.8.2 remains supported**

Harness continues to support ArgoCD 2.8.2 alongside 3.1.8, so you can choose when and how to upgrade. Go to [GitOps Agent version compatibility](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md#what-version-of-gitops-agent-supports-what-version-of-repo-server-and-redis-cache) to review the full matrix.
{% endhint %}

***

## What else changed in ArgoCD 3.x

The following improvements were introduced across the ArgoCD 3.x release series.

### Application controller improvements

The application controller improves resource tracking and state reconciliation. Large deployments with many applications see better performance and more reliable CRD handling. State detection is more accurate, and reconciliation loops complete faster when something drifts from the desired state.

### RBAC enhancements

Role-based access control offers finer-grained permissions for multi-tenant environments. Project-level security is stronger, with clearer separation between teams and roles. If you run ArgoCD in a shared environment, these controls help enforce access boundaries more precisely.

***

## Compatibility and performance notes

The following notes cover compatibility requirements, performance improvements, and observability enhancements included in ArgoCD 3.1.8.

### What works with ArgoCD 3.1.8

ArgoCD 3.1.8 requires Kubernetes 1.20 or later. Upgrade older clusters before you adopt this ArgoCD version. Major Git providers (GitHub, GitLab, Bitbucket, and others) continue to work, and both OAuth and SSH authentication remain supported.

Manifest types are unchanged: Helm charts, Kustomize, and plain YAML work as expected. Kustomize 5.7.0 improves handling of complex configurations.

### Performance gains

Manifest generation and rendering are faster, memory usage for large applications is reduced, and repository caching is more efficient. ApplicationSets that manage multiple applications complete sync operations more quickly.

### Observability

Metrics and monitoring coverage is broader, logging provides clearer diagnostic information, and event reporting includes more detail about application state changes.

***

## Things to watch out for

Review the following areas before upgrading to confirm your existing setup remains compatible.

### Custom plugins

If you built custom config management plugins, go to the [ArgoCD plugin documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/) to review interface changes. Test plugins in a non-production environment before you roll out the upgrade. Plugin interfaces can change between major versions.

### Webhooks and SSO

Webhook configurations remain compatible, and secret validation is stronger. Existing webhook integrations continue without modification. SSO setups (OIDC, SAML, or LDAP) continue to work. OIDC flow improvements run on the server side, so end-user authentication behavior stays the same.

***

## How this affects Harness users

The following sections describe how the ArgoCD 3.1.8 upgrade affects Harness GitOps users.

### Agent compatibility

GitOps Agent version 0.106.0 supports both ArgoCD 2.8.2 and 3.1.8, so you control upgrade timing. You can test 3.1.8 in development while keeping production on 2.8.2, or upgrade all environments together. Go to [GitOps Agent version compatibility](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md#what-version-of-gitops-agent-supports-what-version-of-repo-server-and-redis-cache) to review the complete compatibility matrix.

### Feature compatibility

All Harness GitOps features work with ArgoCD 3.1.8 without modification. ApplicationSets, PR Pipelines, multi-source applications, secret expressions in manifests, and the GitOps sync step in Continuous Delivery pipelines continue to function as before.

### Workflow continuity

The upgrade is designed to leave existing workflows intact. GitOps applications continue running without changes, pipeline configurations remain the same, and repository and cluster connections work as configured. The upgrade does not interrupt deployment processes or require reconfiguring integrations.

***

## Next steps

* [ArgoCD 3.1.8 release notes](https://github.com/argoproj/argo-cd/releases/tag/v3.1.8): Upstream release details for this ArgoCD version.
* [ArgoCD upgrade guide overview](https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/overview/): Official upgrade planning guidance.
* [argo-cd Helm chart releases](https://github.com/argoproj/argo-helm/releases): Chart changelog for the 9.0.0 major bump.
* [Helm chart version 9.0.0 changes](https://github.com/argoproj/argo-helm/releases/tag/argo-cd-9.0.0): Specific chart release notes.
* [GitOps Agent installation](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md): Install or upgrade the Harness GitOps Agent.
* [GitOps architecture](/continuous-delivery/use-gitops/get-started/gitops-architecture.md): How Harness GitOps components fit together.
* [GitOps troubleshooting](/continuous-delivery/use-gitops/resources/troubleshooting.md): Common GitOps Agent and sync issues.
* [Supported Continuous Delivery integrations](/continuous-delivery/new-to-continuous-delivery/cd-integrations.md): Platform and tool support matrix.
* [GitOps release notes for Agent 0.106.0](https://developer.harness.io/release-notes/continuous-delivery/gitops-continuous-delivery#gitops-service-1470-gitops-agent-01060): Harness release announcement for this ArgoCD upgrade.

{% @harness-feedback/feedback %}