> 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/application/applications-in-any-namespace.md).
# Applications in any namespace
Configure your GitOps agent to deploy Argo CD applications into namespaces other than the agent namespace.
By default, Harness GitOps deploys Argo CD Application resources into the namespace where the GitOps Agent is installed. The **Applications in any namespace** feature lets you deploy Application resources into other namespaces on the same cluster, which enables multi-tenancy and self-service workflows for application teams.
Each participating namespace must be declared in two places:
* The agent's **Application Namespaces** field, which tells the agent's informer which namespaces to watch.
* The AppProject's `sourceNamespaces` field, which enforces the security boundary and controls which namespaces can host Applications that belong to the project.
***
### Before you begin
* **Cluster-wide agent required.** The agent must be installed in cluster-wide mode (`isNamespaced=false`). Namespace-scoped agents and Harness Hosted agents do not support this feature.
* **AppProject access.** You need permission to create or edit AppProjects in Harness. Go to [Manage permissions](/continuous-delivery/use-gitops/application/manage-permissions.md) to review the required roles.
* **Existing resources are unaffected.** Enabling Application Namespaces on an agent does not change existing applications. They continue to run without any migration.
***
### Enable Application Namespaces on a new agent
When you create a new agent in Harness, the **Application Namespaces** field is under **Advanced** > **Argo CD Settings** in the agent creation wizard.
1. In your Harness project, go to **GitOps** and select **Settings > GitOps Agents**.
2. Select **New GitOps Agent**.
3. Complete the agent configuration steps.
4. Expand **Advanced** and select **Argo CD Settings**.
5. In the **Application Namespaces** field, enter a comma-separated list of namespaces the agent should watch.
* Enter `*` to allow all namespaces on the cluster.
* Leave the field empty to default to the agent's own namespace only.
6. Finish creating the agent and install the generated manifests on your cluster.
***
### Update Application Namespaces after agent creation
You cannot update the **Application Namespaces** value through the agent API or the Harness UI after the agent is created. The only supported path is the **Generate YAML** workflow.
1. In your Harness project, go to **GitOps** and select **Settings > GitOps Agents**.
2. Select the agent you want to update.
3. Select **Generate YAML**, expand **Advanced**, select **Argo CD Settings**, and update the **Application Namespaces** field.
4. Download or copy the regenerated manifests.
5. Apply the updated manifests on your cluster.
The source of truth for the agent's namespace configuration is the `argocd-cmd-params-cm` ConfigMap on the cluster. If you edit this ConfigMap directly outside of Harness, the Harness UI will show stale configuration until you regenerate and re-apply the manifests through Harness.
***
### Configure AppProject source namespaces
The `sourceNamespaces` field on an AppProject controls which namespaces are permitted to host Application resources that belong to the project. Without this field, only the agent namespace is allowed.
#### Create or edit an AppProject with source namespaces
1. In your Harness project, go to **GitOps** and select **Settings > AppProjects**.
2. Create a new AppProject or open an existing one.
3. In the **Source Namespaces** field, enter the namespaces that are permitted to host applications.
* Use a specific name such as `my-team-ns`.
* Use a wildcard pattern such as `team-*` to match all namespaces that start with `team-`.
* Use a regex pattern such as `/^team-[a-z]+$/` for more precise matching.
* Use `*` to allow all namespaces.
4. Save the AppProject.
#### Example: Terraform configuration
```hcl
resource "harness_platform_gitops_app_project" "example" {
agent_id = "my-agent"
org_id = var.org_id
project_id = var.project_id
upsert = true
project {
metadata {
name = "my-app-project"
namespace = "argocd" # namespace where the agent is installed
finalizers = ["resources-finalizer.argocd.argoproj.io"]
}
spec {
destinations {
namespace = "my-team-ns"
server = "https://kubernetes.default.svc"
}
source_namespaces = ["my-team-ns"]
source_repos = ["*"]
orphaned_resources {
warn = "false"
}
}
}
}
```
***
### Create an application in a non-default namespace
When you create a GitOps application in Harness, the **Source Namespace** field in the application metadata controls where the Application resource is deployed.
* If you leave **Source Namespace** empty, the Application resource is deployed in the agent namespace.
* If you set a value in **Source Namespace**, the Application resource is deployed in that namespace. The namespace must be listed in both the agent's Application Namespaces and the AppProject's `sourceNamespaces`.
* The **destination namespace** is separate from **Source Namespace**. It is where the application's workload resources are deployed and can differ from the namespace that hosts the Application CR.
#### Example: Terraform configuration
```hcl
resource "harness_platform_gitops_applications" "example" {
application {
metadata {
name = "my-app"
namespace = "my-team-ns" # Source Namespace: Application CR location
}
spec {
project = "my-app-project"
source {
repo_url = "https://github.com/my-org/my-repo.git"
path = "apps/my-app"
target_revision = "main"
}
destination {
namespace = "my-app-workloads" # where deployed resources run
server = "https://kubernetes.default.svc"
}
sync_policy {
automated {
self_heal = true
prune = true
}
}
}
}
org_id = var.org_id
project_id = var.project_id
agent_id = "my-agent"
cluster_id = "in-cluster"
repo_id = "my-repo"
name = "my-app"
}
```
The `namespace` in `application.metadata` is the **Source Namespace**. It is set on Create and is **immutable**. An Update request that changes this field returns a `400` error. To move an Application CR to a different namespace, delete and recreate the application.
***
### How Harness names applications
Harness allows multiple applications with the same name in different source namespaces on the same agent. To keep each application unique in Harness, the system prefixes the source namespace to the application name when **Source Namespace** differs from the agent namespace.
* **Prefixed names:** An application named `app1` in source namespace `ns1` is stored in Harness as `ns1/app1`. An application named `app2` in source namespace `ns2` is stored as `ns2/app2`.
* **Same name across namespaces:** Two applications both named `app1` in source namespaces `ns1` and `ns2` are stored as `ns1/app1` and `ns2/app1`.
* **Agent namespace:** If **Source Namespace** matches the agent namespace, Harness stores the application by name only with no namespace prefix.
***
### Resource tracking recommendation
When Application Namespaces is enabled, Argo CD generates tracking labels in the format `namespace/app-name`. Kubernetes labels have a 63-character limit, so application names that result in a combined `namespace/name` string longer than 63 characters cause tracking failures.
Harness recommends switching to **annotation-based tracking** or **annotation+label tracking** when you use Application Namespaces. Annotation values are not subject to the 63-character limit.
Go to [Manage Argo CD configs](/continuous-delivery/use-gitops/connect-and-manage/manage-argo-configs.md) to configure the resource tracking method for your agent.
***
### Known limitations
* **ApplicationSets cannot generate applications in a different namespace.** An ApplicationSet must live in the same namespace as the applications it generates. This is an upstream Argo CD limitation tracked in [issue #11104](https://github.com/argoproj/argo-cd/issues/11104).
* **Namespace-scoped agents are not supported.** Only cluster-wide agents (`isNamespaced=false`) support Application Namespaces.
* **Harness Hosted agents are not supported.** Application Namespaces is only available for self-managed agents.
* **Filtering applications by CR namespace in the application list is not yet available.** This is deferred to a future release.
***
### Troubleshooting
GitOps application fails with 'namespace is not permitted' when using a non-default namespace
Here are the key checks and steps to resolve a "namespace is not permitted" error in a Harness GitOps application:
* **Avoid reserved/system namespaces.** Apps deployed to `kube-system` will not appear in GitOps reconciliation or UI. Use a dedicated namespace instead. \[[GitOps Troubleshooting](https://developer.harness.io/docs/continuous-delivery/gitops/resources/troubleshooting#applications-missing-in-gitops-for-kube-system-namespace)]
* **Check for OPA/Policy violations.** If your account has OPA policies enforcing namespace restrictions (e.g., blocking `kube-system`, `kube-public`, `argocd`, `istio-system`, etc.), your application's destination namespace may be explicitly denied. Review active policies in your project settings. \[[OPA Policy Support](https://developer.harness.io/docs/continuous-delivery/gitops/application/opa-policy-support/#example-block-protected-namespaces)]
* **Verify the destination namespace in the Application config.** When creating or editing the GitOps Application, ensure the **Destination > Namespace** field is set to a valid, non-reserved namespace (e.g., `guestbook`, `my-app-ns`). \[[GitOps Applications](https://developer.harness.io/docs/continuous-delivery/get-started/tutorials/kubernetes-container-deployments/manifest/#applications)]
* **Check for Applications in Any Namespace support.** If you need ArgoCD Application resources in namespaces other than the agent's install namespace, ensure you are using a **cluster-scoped agent** and have configured `applicationNamespaces` accordingly. Namespace-scoped agents do not support this feature. \[[Release Notes](https://developer.harness.io/release-notes/continuous-delivery/#gitops-service-1610-gitops-agent-01210)]
* **Review RBAC and role assignments.** Confirm the user has the correct role assignments in Harness and that application labels match any resource group filters. \[[Manage Permissions](https://developer.harness.io/docs/continuous-delivery/gitops/application/manage-permissions#troubleshooting)]
* **Check ArgoCD project field (Argo CD 2.12+).** If using Argo CD 2.12 or later, the `project` field is now mandatory. Ensure the application's project field matches the project field on the cluster/repo secret, or unset the project field on the secret to allow cross-project access. \[[GitOps Troubleshooting](https://developer.harness.io/docs/continuous-delivery/gitops/resources/troubleshooting#application-creation-fails-due-to-missing-project-field-argo-cd-212-change-previously-it-was-optional)]
* **OpenShift clusters only:** If running on OpenShift, the default `restricted` SCC may block agent components. Grant the required SCCs (`nonroot-v2`, `anyuid`) to the relevant service accounts in your GitOps namespace. \[[OpenShift SCC](https://developer.harness.io/docs/continuous-delivery/gitops/resources/troubleshooting#openshift-security-context-constraints-scc-for-gitops-agent)]
GitOps agent informer does not see applications after enabling Application Namespaces
I'm sorry, but the knowledge sources do not contain enough information to provide a detailed troubleshooting guide specifically for the GitOps agent informer not seeing applications after enabling Application Namespaces.
What the knowledge sources do confirm is:
* **Applications in Any Namespace** is a feature introduced in GitOps Service 1.61.0 / Agent 0.121.0. [June 2026 release notes](https://developer.harness.io/release-notes/continuous-delivery/#gitops-service-1610-gitops-agent-01210)
* It requires a **cluster-scoped agent** — namespace-scoped agents are **not supported** for this feature. [June 2026 release notes](https://developer.harness.io/release-notes/continuous-delivery/#gitops-service-1610-gitops-agent-01210)
Based on the available information, here are the checks you can perform:
* **Verify agent type:** Confirm your agent is cluster-scoped, not namespace-scoped. Namespace-scoped agents do not support Applications in Any Namespace.
* **Check `applicationNamespaces` configuration:** Ensure the `applicationNamespaces` field is correctly specified in your cluster-scoped agent configuration to include the target namespaces.
* **Avoid `kube-system`:** Do not deploy non-system applications to the `kube-system` namespace, as apps in that reserved namespace will not appear in GitOps reconciliation or the UI. [Troubleshooting docs](https://developer.harness.io/docs/continuous-delivery/gitops/resources/troubleshooting#applications-missing-in-gitops-for-kube-system-namespace)
* **Verify agent version:** Ensure you are running GitOps Agent **0.121.0** or later, as this is the minimum version supporting this feature.
* **Check agent health:** In the Harness UI, navigate to **GitOps → Settings → GitOps Agents** and confirm the agent shows a **Healthy** status.
* **Review agent logs:** Check the `argocd-application-controller` and `gitops-agent` pod logs for any errors related to namespace watching or RBAC.
For more detailed troubleshooting beyond these checks, I'd recommend reaching out to [Harness Support](https://support.harness.io/) or consulting the Harness community forums.
AppProject sourceNamespaces configuration is rejected when creating a GitOps application via Terraform
I'm sorry, but the knowledge sources do not contain enough information specifically about Terraform-based GitOps application creation rejecting `sourceNamespaces` in an `AppProject` configuration. However, based on the available documentation, here are relevant checks to investigate:
* **Verify the `sourceNamespaces` field format** — In the `AppProjectSpec`, `sourceNamespaces` is an array of strings. Ensure your Terraform resource passes it as a list, e.g.:
```hcl
source_namespaces = ["namespace-a", "namespace-b"]
```
\[[AppProjectSpec model](https://apidocs.harness.io/)]
* **Include required Argo CD 2.12 fields** — Since Argo CD 2.12, the `project` field is now **mandatory** for repository access. Ensure your application configuration explicitly includes the `project` field, or the creation will fail. \[[Troubleshooting GitOps](https://developer.harness.io/docs/continuous-delivery/gitops/resources/troubleshooting#application-creation-fails-due-to-missing-project-field-argo-cd-212-change-previously-it-was-optional)]
* **Check AppProject metadata labels** — When managing an `AppProject` via Git/Terraform, the following labels are **required**:
* `accountId` (hashed form `b..e`)
* `orgId`
* `projectId`
Missing these will cause the AppProject to be rejected. \[[Manage Argo Configs](https://developer.harness.io/docs/continuous-delivery/gitops/connect-and-manage/manage-argo-configs/#sample-argo-appproject-configuration)]
* **Ensure the AppProject is mapped to the Harness project** — After creating a new AppProject, add the [mapping for the Argo project to the Harness project in the GitOps Agent](https://developer.harness.io/docs/continuous-delivery/gitops/connect-and-manage/multiple-argo-to-single-harness). \[[Manage Argo Configs](https://developer.harness.io/docs/continuous-delivery/gitops/connect-and-manage/manage-argo-configs/#sample-argo-appproject-configuration)]
* **Review cluster secret scoping** — If your cluster secret is scoped to a specific project, applications in other projects will be denied access. Unset the `project` field on the cluster secret if it needs to be shared across projects. \[[Troubleshooting GitOps](https://developer.harness.io/docs/continuous-delivery/gitops/resources/troubleshooting#application-creation-fails-due-to-missing-project-field-argo-cd-212-change-previously-it-was-optional)]
* **Check GitOps agent permissions** — Ensure the GitOps agent has the required access permissions to create/update AppProject resources. \[[GitOps FAQs](https://developer.harness.io/docs/continuous-delivery/gitops/resources/gitops-faqs#how-can-users-set-up-gitops-correctly-and-avoid-configuration-errors)]
For a more targeted diagnosis, I'd recommend checking the Harness GitOps agent logs and the exact error message returned when the Terraform apply fails, then reaching out to [Harness Support](https://support.harness.io/) with those details.
Harness GitOps UI shows stale Application Namespaces configuration after editing argocd-cmd-params-cm directly on the cluster
I'm sorry, but the knowledge sources do not contain enough information to directly address stale Application Namespaces configuration in the Harness GitOps UI after editing `argocd-cmd-params-cm` directly on the cluster.
However, based on related concepts in the knowledge sources, here are some checks and steps that may help:
* **Trigger a Refresh** — In the Harness GitOps UI, go to **Deployments > GitOps > Applications** and click **Refresh** for the affected application. This pulls the latest commit from Git and updates the sync state, though it does not directly sync live cluster state. \[[GitOps basics](https://developer.harness.io/docs/continuous-delivery/gitops/get-started/harness-git-ops-basics#operational-concepts)]
* **Check agent reconciliation timing** — The GitOps agent reconciles on CRUD events every \~10 seconds and runs a bulk reconciliation every \~100 seconds. If the UI still shows stale data, wait for a full reconciliation cycle to complete. \[[Agent reconciliation](https://developer.harness.io/docs/continuous-delivery/gitops/gitops-entities/agents/install-a-harness-git-ops-agent#considerations)]
* **Restart the GitOps agent** — Direct edits to `argocd-cmd-params-cm` on the cluster require an agent restart to take effect. Run `kubectl rollout restart deployment -n argocd ` to apply the new configuration. \[[BYOA troubleshooting](https://developer.harness.io/docs/continuous-delivery/gitops/resources/troubleshooting#issue-agent-degraded-when-installing-a-bring-your-own-argo-cd-byoa-agent-with-a-helm-chart)]
* **Manage Argo CD config declaratively via Harness GitOps** — Instead of editing `argocd-cmd-params-cm` directly, consider managing Argo CD configurations (including `applicationNamespaces`) as Git-backed manifests through a Harness GitOps application. This ensures the UI always reflects the desired state in Git. \[[Manage Argo configs](https://developer.harness.io/docs/continuous-delivery/gitops/connect-and-manage/manage-argo-configs/)]
* **Verify agent version** — Ensure your GitOps agent is on version **0.93 or higher** for reliable bulk sync/refresh behavior, and **0.89 or higher** to avoid duplicate reconciliation issues in HA setups. \[[Bulk Sync](https://developer.harness.io/docs/continuous-delivery/gitops/application/sync-gitops-applications#bulk-sync-and-refresh); [Agent reconciliation](https://developer.harness.io/docs/continuous-delivery/gitops/gitops-entities/agents/install-a-harness-git-ops-agent#considerations)]
* **Contact Harness Support** — If the UI continues to show stale data after the above steps, reach out to for further investigation, as this specific scenario is not fully covered in the available documentation.
***
### Next steps
* Go to [Manage AppProjects](/continuous-delivery/use-gitops/gitops-entities/projects/manage-projects.md) to configure source namespaces and destinations on your AppProjects.
* Go to [Install a Harness GitOps Agent](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md) to review agent installation options and cluster-wide mode requirements.
* Go to [Manage Argo CD configs](/continuous-delivery/use-gitops/connect-and-manage/manage-argo-configs.md) to configure annotation-based resource tracking.
{% @harness-feedback/feedback %}