> 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/connect-and-manage/multiple-argo-to-single-harness.md).

# Bring Your Own Argo CD into Harness GitOps

This topic describes how to import your existing Argo CD configuration into Harness GitOps as a Bring Your Own Argo CD (BYOA) setup.

In addition, when you install the Harness GitOps Agent in your existing Argo CD cluster as part of BYOA, you can map Argo CD projects to Harness projects. Harness imports all the Argo CD project entities (applications, clusters, repos, etc.) and creates them in Harness automatically.

Also, whenever new entities are created in the mapped Argo CD projects, they are added to Harness automatically.

With a standard Harness GitOps Agent installation (non-BYOA), Harness can install and manage Argo CD for you. This scenario is different from a BYOA where you are importing an existing Argo CD configuration into Harness GitOps.

For more information, go to [Install a Harness GitOps Agent](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md).

#### Mapping existing Argo CD projects across different Harness scopes <a href="#mapping-existing-argo-cd-projects-across-different-harness-scopes" id="mapping-existing-argo-cd-projects-across-different-harness-scopes"></a>

To map Argo CD projects to Harness projects, you need to install the Harness GitOps Agent from the Harness account or organization level. Then you can map the Argo CD projects to any of the Harness projects in the account or organizations.

If you install the GitOps Agent at the Harness project level, you can only map to the current project.

The following example installs the GitOps Agent at the Harness account level.

### Installing a GitOps Agent in an existing Argo CD setup (BYOA) <a href="#installing-a-gitops-agent-in-an-existing-argo-cd-setup-byoa" id="installing-a-gitops-agent-in-an-existing-argo-cd-setup-byoa"></a>

The following steps show you how to install a GitOps Agent into an existing Argo CD namespace and then map your existing projects to your Harness project.

1. In your Harness account, select **Account Settings**.
2. Select **GitOps**, and then select **Agents**.

   ![](/files/wAmqNP3Qi29YTABk2plM)
3. Select **New GitOps Agent**.
4. In **Agent Installation**, in **Do you have any existing Argo CD instances**, select **Yes**, and then select **Start**.

   ![](/files/72nJhN87we9DAphd3KIR)
5. In **Name**, enter a name for your agent, such as `byoa-agent`.
6. In **GitOps Operator**, select **Argo**. Argo CD is the only supported GitOps reconciler. Flux is not supported.
7. In **Namespace**, enter the namespace where Argo CD is hosted. The default is `argocd`.

   ![](/files/Ft684iwDgoKNtPHyv7tB)
8. Select **Continue**.
9. In **Review YAML**, select **Download & Continue**.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Alternatively, the <strong>Helm Chart</strong> option lets you download a <code>helm-chart</code> file for the Harness GitOps Agent. You can download this file and install it in your Harness GitOps Agent cluster if you prefer using Helm.</p><p>You can download an <code>override.yaml</code> file which will contain the Helm Value overrides to apply, and you can use the commands mentioned to install the agent using the <a href="https://harness.github.io/gitops-helm/">public Helm Repository</a> for the GitOps Agent.</p></div>
10. Log in to the cluster hosting Argo CD.
11. Run the install command provided in the Agent installer, such as `kubectl apply -f gitops-agent.yml -n argocd`. You'll see output similar to this:

    ```bash
    serviceaccount/gitops-agent created
    serviceaccount/gitops-agent-upgrader created
    secret/gitops-agent created
    configmap/gitops-agent created
    configmap/gitops-agent-upgrader created
    clusterrole.rbac.authorization.k8s.io/byoa-agent-agent created
    clusterrolebinding.rbac.authorization.k8s.io/byoa-agent-agent created
    role.rbac.authorization.k8s.io/gitops-agent created
    role.rbac.authorization.k8s.io/gitops-agent-upgrader created
    rolebinding.rbac.authorization.k8s.io/gitops-agent created
    rolebinding.rbac.authorization.k8s.io/gitops-agent-upgrader created
    deployment.apps/gitops-agent created
    cronjob.batch/gitops-agent-upgrader created
    ```

    <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>CONFIGURE HIGHAVAILABILITY FLAG</strong></p><p>After installation, configure the <code>highAvailability</code> flag to match your Redis deployment using <code>helm upgrade</code>. If not set correctly, the agent shows <strong>DEGRADED</strong> status. Run <code>helm upgrade gitops-agent harness/gitops-agent -n harness-gitops --set highAvailability=&#x3C;true|false></code> to update the flag. Go to <a href="/pages/IvY2ev8sOVy2KfDu4a8p#the-highavailability-flag">The highAvailability flag</a> for explanation and <a href="/pages/hV24UXDt8F3Aj9fBxhr4#agent-shows-degraded-with-redis-cache-installed-health-check-failure">Troubleshooting</a> for solutions.</p></div>
12. In the Harness GitOps Agent installer, select **Continue**.

The Agent has registered with Harness.

![](/files/0AiSQLB53aTu33ZenNfu)

13. Select **Continue**. The **Map Projects** settings appear.

{% hint style="warning" %}
Ensure that you deploy only one Harness GitOps Agent per Argo CD namespace. Deploying multiple Agents created in different projects or accounts can lead to unpredictable behavior.

Harness supports mapping Argo CD projects into Harness projects through the Agent that controls the Argo CD deployment. When importing Argo CD projects, Harness maps Argo CD projects into Harness projects that belong to one account.

Enabling multiple Agents in one Argo CD namespace implies cross-account resource sharing which Harness does not support.
{% endhint %}

### Map existing Argo projects <a href="#map-existing-argo-projects" id="map-existing-argo-projects"></a>

To map your existing Argo CD projects to Harness projects, select the Argo CD projects you want to use, and then select the Harness project where you want to map the Argo CD project.

1. In **Map Projects**, in **Select your Argo Projects to Import**, select the Argo CD projects you want to map.

   ![](/files/6vylBJo6zrfd90wl7XUj)
2. In each row, select the Argo project and the Harness project.

   ![](/files/zm57hnO08LLk5VHeJPgH)

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Do not map the same Argo CD project to multiple Harness projects.</p></div>
3. To automatically create Harness services and environments during the import, enable the **Enables automatic creation of service environments** toggle on the Map Projects screen.

   ![](/files/rnBcLru9fG0ANYDbH4gg)

   When this toggle is enabled, Harness checks each Argo CD application for `harness.io/serviceRef` and `harness.io/envRef` labels. If a service or environment matching the label value already exists in the target Harness project, the application is mapped to it. If it does not exist, Harness creates the service or environment automatically and then maps it to the application.

   To use this feature, add the `harness.io/serviceRef` and `harness.io/envRef` labels to the `metadata.labels` section of your Argo CD Application YAML before importing.

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>IDENTIFIER NAMING RULES</strong></p><p>The <code>harness.io/serviceRef</code> and <code>harness.io/envRef</code> label values become Harness entity identifiers. They must follow these rules:</p><ul><li>Must start with a letter or underscore (not a number or <code>$</code>).</li><li>Can only contain alphanumeric characters, underscores (<code>_</code>), and dollar signs (<code>$</code>).</li><li>Maximum length: 128 characters.</li><li>Cannot use reserved keywords: <code>or</code>, <code>and</code>, <code>eq</code>, <code>ne</code>, <code>lt</code>, <code>gt</code>, <code>le</code>, <code>ge</code>, <code>div</code>, <code>mod</code>, <code>not</code>, <code>null</code>, <code>true</code>, <code>false</code>, <code>new</code>, <code>var</code>, <code>return</code>, <code>step</code>, <code>parallel</code>, <code>stepGroup</code>, <code>org</code>, <code>account</code>, <code>class</code>, <code>shellScriptProvisioner</code>.</li></ul><p><strong>Valid examples:</strong> <code>my_service</code>, <code>MyService123</code>, <code>_internal_service</code>, <code>service_v2$backup</code></p><p><strong>Invalid examples:</strong> <code>123service</code> (starts with number), <code>$service</code> (starts with <code>$</code>), <code>my-service</code> (contains hyphen), <code>my.service</code> (contains dot), <code>org</code> (reserved keyword)</p><p>If a label value does not follow these rules, the auto-creation fails silently for that application.</p></div>

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>If you are using ApplicationSets, you can templatize the <code>harness.io/serviceRef</code> and <code>harness.io/envRef</code> labels so that every generated application automatically includes them. For details, go to <a href="/pages/YcmadbMni553SC0ERrrJ#auto-create-services-and-environments">Auto-create services and environments with ApplicationSets</a>.</p></div>
4. Select **Import & Continue**.

   The Argo CD projects are imported. When auto-creation is enabled, the import summary also shows the number of services, environments, and cluster links created or mapped.

   ![](/files/MSDyeny2La8tSGeqZJpX)
5. Select **Finish**. The mapping is displayed in the Agent details.

   ![](/files/TiBhtyAtCc0THTV2uedR)
6. Select **Save**.

### Verify mapping <a href="#verify-mapping" id="verify-mapping"></a>

To see the imported Argo CD entities from the mapping, look in the mapped Harness project.

1. In your Harness project, select **GitOps**, and then select **Applications**. You can see the imported applications.

   ![](/files/OXm6sWE0YJHKhcvAp30D)
2. Select **Settings**, and then select **Repositories**. You can see the imported repositories.
3. Select **Settings**, and then select **Clusters**. You can see the imported clusters.

Do the same for any other mapped project entities.

#### Verify auto-created services and environments <a href="#verify-auto-created-services-and-environments" id="verify-auto-created-services-and-environments"></a>

If you enabled the **Enables automatic creation of service environments** toggle during the import, verify that the services and environments were created correctly.

1. In your Harness project, select **Services** in the left navigation. You can see the services that Harness created automatically based on the `harness.io/serviceRef` labels in your application manifests.

   ![](/files/EB7ivcaLobWtmJDWKTF0)
2. Select **Environments** in the left navigation. You can see the environments that Harness created based on the `harness.io/envRef` labels.

   ![](/files/khxicOq0jLz4gQsnBvIm)
3. To confirm that an application is mapped to the correct service and environment, go to **GitOps** > **Applications**, select an application, and open the **App Details** tab. The **Service** and **Environment** fields display the mapped values.

   ![](/files/jfBTKKOKQdYIos5CV0J2)

### Adding new mappings to existing Agent <a href="#adding-new-mappings-to-existing-agent" id="adding-new-mappings-to-existing-agent"></a>

You can add new mappings to an existing Agent in the Agent's **Mapped Harness Project** settings.

{% hint style="warning" %}
**REDIS CACHE TIMEOUT WHEN RE-ADDING A PROJECT MAPPING**

If you remove a project mapping and immediately re-add or re-import it, the autocreate flow for services and environments may not trigger. This is because the Reconcile Application process has a 29-second Redis cache timeout. Wait at least 30 seconds after removing a project mapping before adding it back to ensure the autocreate flow works as expected.
{% endhint %}

1. In Harness, open an existing Agent.
2. Select **Edit**. In this example, the Argo CD project **alpha** is mapped to the Harness project **GitOps**.

   ![](/files/stjUe7ftpf6IyzgBmarV)

   Let's add a new mapping.
3. In **Mapped Harness Project**, select **Add**.
4. In **Map Projects**, in **Select your Argo Projects to Import**, select an Argo CD project. Do not select a project you have already mapped.
5. Map the Argo CD project to a Harness project and select **Import & Continue**. Do not re-map an existing mapping. Harness will throw an error.

   ![](/files/fOjhQ91RG1xyWbzHHETn)
6. When the import is complete, select **Finish**.

Both projects are now mapped.

![](/files/dhuuDuTtVr5xzwmvnr0s)

### Adding Argo CD entities to Harness automatically <a href="#adding-argo-cd-entities-to-harness-automatically" id="adding-argo-cd-entities-to-harness-automatically"></a>

When an Agent contains Argo CD project mappings to a Harness project, any new entities added to the Argo CD project are added to the mapped Harness project automatically.

Try adding a new Argo CD repository to the mapped Argo CD project.

Once it is saved in Argo CD, go to Harness and look at the GitOps repositories in the mapped Harness project. A new repository is added.

#### Automatically added Argo CD repositories <a href="#automatically-added-argo-cd-repositories" id="automatically-added-argo-cd-repositories"></a>

When Argo CD repositories are added to Harness, Harness automatically generates a name for each repository. Name generation is necessary because Argo CD has no name setting for its repositories. When generating a name for a repository, Harness removes any dashes from the name of the repository, and then appends an underscore followed by a unique suffix.

For example, the Argo CD repository `https://github.com/argoproj/gitops-engine.git` is named `gitopsengine_kmjzyrbs` in Harness.

![](/files/2lyVmZuHbdJ1CcBVdP3f)

#### Ensure your Argo CD entities are visible in Harness <a href="#ensure-your-argo-cd-entities-are-visible-in-harness" id="ensure-your-argo-cd-entities-are-visible-in-harness"></a>

In some Argo CD versions, you are not required to specify a project for your entities. However, for the entities to be visible in Harness, you must associate the entities with a project.

If you are unable to edit an entity from the Argo CD UI, you can edit that entity in the cluster so that they have a project and other required values. The entities are stored in different formats in the cluster. For example, clusters, repositories, and repository credential templates are stored in `Secret`, and GnuPG keys and repository certificates are stored in `ConfigMap` in the namespace where Argo CD is installed.

Edit the respective secret of the entity and add the fields `project` and `name` in the `data` or `stringData` block. For examples, go to [Manage an Argo CD configuration in Git with Harness GitOps](/continuous-delivery/use-gitops/connect-and-manage/manage-argo-configs.md#git-configuration-files).

### Creating GitOps entities with multiple projects <a href="#creating-gitops-entities-with-multiple-projects" id="creating-gitops-entities-with-multiple-projects"></a>

When you have multiple Argo CD projects mapped to your Harness project, you can choose which Argo CD project to use when you create a new GitOps entity (cluster, repository, or application) in your Harness project.

By default, in the Argo CD console, when you create a cluster, it is not associated with an Argo CD project. You can add the cluster by using the `argocd cluster add` CLI and its `--project` option.

The following steps are common to all three entities (clusters, repositories, and applications) when you create them in Harness. We will demonstrate this with GitOps clusters:

1. While creating a GitOps cluster in the Harness project that is mapped to multiple Argo CD projects, under **GitOps Agent**, select the Agent where you set up the mappings. The **Project** setting appears.

   If the Agent has only one Argo CD project mapped, the **Project** setting is not shown.
2. In **Project**, select the Argo CD project with the cluster you want to import.

   ![](/files/P39o93fve8WOTYdxhQdW)

When you have completed [setting up the cluster](/continuous-delivery/use-gitops/get-started/harness-cd-git-ops-quickstart.md#step-3-add-a-harness-gitops-cluster), the cluster appears in the GitOps Cluster list.

### Enable Harness Expression Resolution for Existing Installations <a href="#enable-harness-expression-resolution-for-existing-installations" id="enable-harness-expression-resolution-for-existing-installations"></a>

With a BYOA setup, you can enable the Harness ArgoCD plugin to use Harness secret expressions directly in your application manifests. This feature allows you to reference secrets stored in Harness (such as database passwords, API keys, etc.) within your Kubernetes manifests, and the expressions are resolved and decrypted during manifest rendering.

For feature requirements, supported secret managers, and usage examples, go to [Harness Secret Expressions in Application Manifests](/continuous-delivery/use-gitops/application/manage-gitops-applications.md#harness-secret-expressions-in-application-manifests).

{% hint style="info" %}
For existing Agent installations (BYOA or Harness-installed Argo), the **Enable ArgoCD Harness Plugin** checkbox cannot be changed after the initial installation. You must configure the Harness ArgoCD plugin by running a patch script on your existing Argo CD installation using the instructions below.
{% endhint %}

#### For Helm Chart installations <a href="#for-helm-chart-installations" id="for-helm-chart-installations"></a>

If your GitOps agent was installed using the Harness-provided Helm chart, follow these steps:

1. **Upgrade to the latest chart** and make the following changes to your `values.yaml` file.
2. **Enable the Harness ArgoCD plugin** by adding the following flag:
3. **Add the agent service configuration** under the `agent` section:
4. **Add the plugin container** to the Argo CD repo server by adding the following under `argo-cd.repoServer.extraContainers`:
5. **Add the ConfigMap volume** to the repo server by adding the following under `argo-cd.repoServer.volumes`:
6. **Apply the changes** by running the Helm upgrade command:

   ```bash
   helm upgrade <release-name> gitops-agent/gitops-helm --values values.yaml --namespace <agent-namespace>
   ```

#### For plain Kubernetes manifest installations <a href="#for-plain-kubernetes-manifest-installations" id="for-plain-kubernetes-manifest-installations"></a>

If your GitOps agent was installed using plain Kubernetes manifests, follow these steps:

1. **Create the agent service** (if it doesn't already exist):

   Apply this manifest:

   ```bash
   kubectl apply -f gitops-agent-service.yaml -n <agent-namespace>
   ```
2. **Create the plugin ConfigMap** in the same namespace as your GitOps agent/Argo CD:

   Apply this ConfigMap:

   ```bash
   kubectl apply -f argocd-harness-plugin-configmap.yaml -n <agent-namespace>
   ```
3. **Add the plugin sidecar container** to the `argocd-repo-server` deployment:

   Edit the `argocd-repo-server` deployment and add the following container under `spec.template.spec.containers`:

   Apply the updated deployment:

   ```bash
   kubectl apply -f argocd-repo-server-deployment.yaml -n <agent-namespace>
   ```
4. **Verify the installation** by checking that the plugin container is running:

   ```bash
   kubectl get pods -n <agent-namespace> -l app.kubernetes.io/name=argocd-repo-server
   kubectl logs -n <agent-namespace> <argocd-repo-server-pod> -c argocd-harness-plugin
   ```

#### Verification <a href="#verification" id="verification"></a>

After completing the installation, verify that the Harness plugin is working correctly:

1. Check that the `argocd-repo-server` pods are running with the new sidecar container
2. Verify that the plugin ConfigMap exists in the namespace
3. Test expression resolution by deploying an application with Harness secret expressions

For usage examples and expression syntax, refer to [Harness Secret Expressions in Application Manifests](/continuous-delivery/use-gitops/application/manage-gitops-applications.md#harness-secret-expressions-in-application-manifests).

### Notes <a href="#notes" id="notes"></a>

* Harness honors Argo CD project permissions. If the project selected for the Harness application does not have permissions for the repository or cluster, then Harness returns a permissions-related error. You must go to Argo CD and adjust the project's scoped repositories and destinations.
* A non-BYOA setup does not support mapping multiple Argo CD projects to a single Harness project.
* **Upgrading your Argo CD Version**: If you upgrade your Argo CD version to any version that is >= v2.8.0 with a BYO Argo GitOps agent installed, you will have to restart the agent pods in order for the agent to pickup the required configuration change. You canrestart the deployment or the pods individually.