GitOps FAQs

Answers to common questions about Harness GitOps deployments, agents, repositories, and applications.

This topic answers common questions about Harness GitOps. Go to Harness GitOps basics to review core concepts.

Basics

What is Harness GitOps?

Harness GitOps lets you perform GitOps deployments in Harness. You define the desired state of the service you want to deploy in your Git manifest, and then use Harness GitOps to sync the state with your live Kubernetes cluster. Go to Harness GitOps basics to review core concepts.

Does Harness GitOps support Flux?

No. Harness GitOps supports Argo CD as the only GitOps reconciler. Flux is not supported. If you manage workloads with Flux, go to Migrate from Flux to Argo CD to migrate them to Argo CD with Harness GitOps.

Does Harness provide drift detection for Kubernetes non-GitOps pipelines?

No. Drift detection for Kubernetes non-GitOps pipelines is not supported.

Does Microsoft Teams support full GitOps?

No. Microsoft Teams does not support GitOps.

What is the role of a Deployment Repository in a GitOps service?

The Deployment Repository manifest is deprecated and will stop working on October 4, 2026. It points to your ApplicationSet template YAML in Git, so the Fetch Linked Apps pipeline step can read it to discover which Argo CD applications are generated from the ApplicationSet and linked to your service.

Use App Set Reference instead. It directly references an ApplicationSet managed by a GitOps agent, so you no longer need a Git file for the Fetch Linked Apps step to discover linked applications. Go to App Set Reference to configure it, or go to Migrate Deployment Repo to Application Set references if your service already has a Deployment Repository manifest.

How are App Project IDs generated?

Harness uses the following procedure to calculate the app project ID:

Concatenate the account ID, org ID, and project ID.
Generate the md5 hash for the concatenated string.
The first 8 characters of the hash become the app project ID.

Example:

accountid: prod
orgid: default
projectid: test

concatenated string: proddefaulttest

hash: abcdefghijklmnopqrstuvwxyz

app project id: abcdefgh

GitOps Agent

Can I use Harness GitOps images from a local registry?

Yes. Pull the publicly available images to your private registry, then update the GitOps Agent YAML to reference the private registry.

Can I automate the provisioning of the GitOps Agent without creating the agent in the UI first?

Yes. You can use the API or Terraform, which also dynamically generates the YAML that can be applied. Using Terraform, you can fully automate GitOps Agent provisioning without registering or creating an agent in the UI.

What is the easiest way to determine the Argo CD version used by a GitOps agent?

Create a GitOps agent and inspect the associated manifest to identify the Argo CD version. Go to GitOps Agent documentation to review supported Argo CD versions.

Does the Harness GitOps Agent support High Availability and scalability?

Yes. The Harness GitOps Agent supports High Availability and scalability by allowing you to deploy multiple agents across different clusters. This ensures redundancy and load distribution.

Which versions of Argo CD does the GitOps agent support?

Go to GitOps Agent documentation to find supported Argo CD versions.

Does the GitOps agent updater also update Argo CD and Redis?

No. The agent updater updates agents only when a new version is available. You must upgrade the Argo CD components manually. This is also true when you use the option to bring your own Argo CD.

Do we have a way of adding a certificate at the project or org level for the GitOps Agent?

Certificates cannot be added at different scopes (project, org, or account level) for the GitOps Agent. This is an agent-side configuration and must be done at the agent itself. Go to Harness GitOps Agent with self-signed certificates for more details.

How can I configure the Harness GitOps agent auto updater to use an Artifactory proxy for Docker Hub?

Organizations can import the GitOps image from the Docker Hub repository into JFrog Artifactory. The auto updater feature may not be feasible in this scenario, but you can manually copy the image to Artifactory and pull it from there as an alternative. Go to install a Harness GitOps Agent for more details.

How do I set up TLS in the GitOps Agent?

To set up TLS in the GitOps Agent, mount the certificates onto the Agent deployment:

containers:
  volumeMounts:
  - mountPath: /path/to/cert
    name: your-tls-cert-volume
volumes:
- name: your-tls-cert-volume
  configMap:
    name: your-tls-cert-configMap
    defaultMode: 420

Next, set the SSL_CERT_FILE environment variable in the Agent deployment manifest:

containers:
- command:
    - /app/agent
  name: gitops-agent
  image: harness/gitops-agent:v0.72.0
  imagePullPolicy: Always
  env:
    - SSL_CERT_FILE: "/path/to/cert/crt.pem"

This environment variable tells the Agent to use the file at the specified path for TLS. In this example, the Agent uses /path/to/cert/crt.pem.

How do I disable pushing logs from the GitOps Agent to Stackdriver?

Set GITOPS_AGENT_ENABLE_STACK_DRIVER_LOGGER to False in the agent ConfigMap.

How can I resolve GitOps agent connectivity and authentication failures?

Connectivity failures between the agent and the server typically indicate network or authentication configuration problems. Do the following:

Verify network connectivity between the agent and the server.
Check the agent configuration for the correct server address, port, and authentication credentials.
Review the server logs for errors related to the agent connection attempts.

Go to install a Harness GitOps Agent for more details.

How can I resolve the issue of GitOps agents failing to connect to the GitOps server?

Check the following:

Ensure the agent ConfigMap is correctly set.
Verify that the AGENT_HTTP_TARGET variable is properly defined.
Restart the agent if configuration changes were made.

What should I do if I need to upgrade my Argo CD version after setting up the BYOA agent?

If you upgrade your Argo CD to version 2.8.0 or later, restart the Harness GitOps agent pods to ensure they pick up the necessary configuration changes.

Applications and sync

Why is the GitOps Sync step failing with an "Application does not correspond to the service(s)" error?

This error indicates an inconsistency between the service used in the deploy stage and the selected application. GitOps cannot sync a service that is not correlated to the application.

Application does not correspond to the service(s) selected in the pipeline execution

Application{name: '$APP_NAME', agentIdentifier: '$AGENT_ID', errorMessage: 'Application does not correspond to the service(s) selected in the pipeline execution.'}

To fix this, go to the Continuous Delivery module and select GitOps > Applications, then select the application. In App Details, verify that the service configured for the application matches the service configured in the pipeline deploy stage.

How can I sync or delete an application or non-deployment resource?

Each resource in the UI has a three-dot menu that allows you to sync or delete the resource.

If an application is unreachable on Argo CD and cannot be deleted through the standard flow, use Force delete from Harness in the Delete Application dialog. Go to Manage GitOps Applications to review when this option appears and how to use it.

How do I get a list of all degraded or suspended GitOps applications?

Call the API to get a list of all applications along with their health status:

curl 'https://app.harness.io/gateway/gitops/api/v1/applications?routingId=SNM_3IzhRa6SFPz6DIV7aA' \
  -H 'accept: */*' \
  -H 'accept-language: en-GB,en-US;q=0.9,en;q=0.8' \
  -H 'authorization: Bearer PAT_TOKEN' \
  --data-raw '{"accountIdentifier":"ACCOUNT_ID","orgIdentifier":"ORG_ID","projectIdentifier":"PROJECT_ID"}'

How does the requirement for all applications within an Argo CD ApplicationSet to be managed by the same agent affect usability?

The requirement that all applications within an Argo CD ApplicationSet must be managed by the same agent, despite links being able to connect to multiple clusters, is a known limitation of Argo CD Application Sets. Go to Argo CD ApplicationSet documentation for more details.

How can I manage Argo CD Application Sets using a single Argo CD agent?

Argo CD ApplicationSets do not fully support project-scoped repositories. While you can create an ApplicationSet, the underlying applications may fail to fetch repository contents due to authentication issues. Workarounds:

Use an organization-scoped or account-scoped repository instead of a project-scoped repository.
Configure repo-cred templates to manage authentication for project-level repositories. This is a known limitation tracked in Argo CD.

How can I configure Sync Windows for GitOps applications?

Argo CD allows you to configure Sync Windows to control when auto-sync occurs. You can do this by:

Defining maintenance windows.
Using Sync Windows APIs to set restricted deployment times.

How can I implement better control around GitOps syncs to restrict certain applications?

Fine-grained GitOps RBAC controls are limited.

How do I configure EnvRef and ServiceRef for a GitOps service and environment through Helm?

To associate your GitOps application with a Harness service and environment, add harness.io/envRef and harness.io/serviceRef as labels, not annotations, in your GitOps application manifest.

Key points:

harness.io/envRef and harness.io/serviceRef must be placed under the labels section, not annotations.
envRef should reference your Harness environment identifier.
serviceRef should reference your Harness service identifier.

How can I declaratively create a GitOps application using a YAML manifest?

In Harness GitOps, you can manage applications as code using YAML manifests. The actual Argo CD Application resource resides in the repo that your Harness GitOps application points to, which keeps a clean separation between Harness metadata and the Argo CD application logic.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-argo-app
  namespace: argo-cd
  labels:
    harness.io/envRef: harnessEnvId
    harness.io/serviceRef: harnessServiceId
spec:
  project: default
  source:
    repoURL: https://github.com/org/repo
    path: apps/my-app
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app-namespace
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

The key fields are:

apiVersion and kind: Define the resource type as an Argo CD Application.
metadata.name: The name of your Argo CD application.
metadata.namespace: The namespace where the application is deployed.
spec.project: Points to the Argo CD project. Set this to an Argo project mapped to a Harness project for successful import.
spec.source.repoURL: The URL of the Git repository containing your Kubernetes resources.
spec.source.path: The directory in the repo that contains the Kubernetes manifests.
spec.source.targetRevision: The Git revision (branch or commit) for Argo CD to track.
spec.destination.server: The Kubernetes API server URL.
spec.destination.namespace: The namespace for deployment.
spec.syncPolicy.automated: Specifies automatic sync with pruning and self-healing.

Argo CD and projects

What is the optimal number of Argo CD instances for bootstrapping environments and managing GitOps infrastructure?

Installing the Argo CD reconciler concurrently with environment creation streamlines the execution of GitOps practices at scale and reduces the complexity of bootstrapping environments. Go to the Argo CD, Terraform, and Harness blog to review the recommended approach.

Can I map multiple Argo CD projects to a single Harness project?

No. You cannot map the same Argo CD project to multiple Harness projects. Each Argo CD project must be mapped to a unique Harness project.

What happens if I add new entities to my Argo CD project after mapping it to Harness?

Any new entities added to the mapped Argo CD project are automatically imported into the corresponding Harness project, ensuring synchronization between both platforms.

How can I verify that my Argo CD entities are correctly imported and visible in Harness?

After mapping, navigate to your Harness project and select GitOps, then check under Applications, Repositories, and Clusters to confirm the imported entities.

How does Harness handle naming for Argo CD repositories when they are imported?

Harness automatically generates names for Argo CD repositories during the import process by removing dashes and appending a unique suffix. This ensures each repository has a distinct name within Harness.

Repositories and clusters

Do we support OCI repositories and automation for adding new repositories in GitOps?

Yes. Go to Helm OCI repository documentation for more details.

Does Bitbucket work as a GitOps repository source?

Yes. Bitbucket is supported. Any Git provider that Argo supports is also supported by Harness GitOps. Go to Argo CD Access Token documentation for configuration details.

Where are repository and cluster details stored in Argo CD or the agent?

Repository and cluster details are stored as secrets in the namespace where Argo CD or the agent is installed. ConfigMaps and secrets manage cluster information and repository details, and these are saved directly on the cluster where the agent is deployed.

What could cause a 403 Forbidden error when fetching an anonymous token for a repository?

A 403 Forbidden error typically occurs due to insufficient permissions or incorrect repository configuration. The credentials used may lack the required access, or the repository details may be misconfigured.

How can I verify that the credentials used for a repository are correct?

Do the following to verify credentials:

Ensure the correct username and token or SSH key are being used.
Check the secret storing the repository credentials in the namespace where Argo CD or the agent is deployed.
Confirm that the repository permissions align with the required access levels.

What happens if repository or cluster credentials are incorrect?

If the credentials are incorrect, operations like fetching repository details, deploying to clusters, or synchronizing changes will fail, often resulting in errors such as 403 Forbidden or authentication failures.

How can I fix a 403 Forbidden error for a repository in Argo CD or the agent?

To resolve the error:

Verify that the repository credentials stored in the secret are correct.
Ensure the user or token has the appropriate access permissions for the repository.
Check if the repository URL is configured correctly in the repository secret or ConfigMap.

How can I resolve the issue of clusters not appearing in the CD pipeline?

Verify that the agent, cluster, and service are set up correctly. After linking the clusters to your environment in the GitOps section, re-test the pipeline to confirm the issue is resolved.

What should I do if the cluster linking problem persists?

Double-check the cluster, agent, and service configurations in both Harness and your GitOps setup. If the issue persists, contact your Harness support team with detailed logs or screenshots.

How can I address the unexpected behavior of linking a GitOps cluster to an environment when a link already exists?

The insert call creates a new link, but there is also an update call that updates the existing link. Use the update call to modify an existing link instead of creating a duplicate.

Permissions and security

Which RBAC policies or permissions are required to use Harness GitOps?

The minimum RBAC requirements depend on the applications and destination cluster setup, so they are not straightforward to determine without that context. The Argo CD application controller has wide RBAC permissions by default.

Can I pass sensitive data in a Harness GitOps deployment?

Yes. Use Mozilla SOPS to securely manage sensitive data by encrypting it before storing it in your Git repository. SOPS decrypts the data during deployment using keys stored as Kubernetes secrets, ensuring sensitive information remains protected.

How can I set up GitOps correctly and avoid configuration errors?

Ensure the following:

Correct repository configurations are set in the GitOps settings.
Proper sync policies are in place.
Required access permissions are granted for GitOps agents.

How can I troubleshoot authentication issues when using an existing Argo CD with service prefixes?

Check the following:

Ensure correct environment variables are set for Redis and Repo connections.
Validate that the GitOps agent is properly configured and has the necessary permissions.

What needs to be enabled to fix the "in-cluster has been disabled" error when adding a GitOps agent?

Update the ConfigMap to enable in-cluster support by setting cluster.inClusterEnabled: 'true'.

PreviousResources

NextTroubleshooting

Last updated 7 days ago

Was this helpful?