Troubleshooting GitOps Runtime installation

Review how to resolve issues during Runtime installation

Troubleshooting Runtime installation

This article describes potential issues you may encounter when installing the GitOps Runtime, whether you’re using an existing Argo CD instance or setting up a new one.

Error: Job has reached the specified backoff limit

This error appears when you copy and run the Install Runtime command in the Runtime Installation wizard. Before starting the installation, GitOps Cloud automatically validates the values.yaml file to ensure the supplied values are correct.

Possible cause

Validation errors in your values.yaml file.

Resolution

  1. Get more detailed information on the reason for the validation failure by running:
    kubectl logs jobs/validate-values -n ${NAMESPACE}
    where:
    {NAMESPACE} is the namespace of the Hybrid GitOps Runtime.
  2. Fix the errors. The table below describes the settings that are validated in the values file.
Setting Validation
userToken If explicitly defined, or defined as a secretKeyRef which exists in the current k8s context and the defined namespace.
Account permissions If the user has admin permissions for the account in which they are installing the runtime.
Runtime name If defined, and is unique to the account.
Access mode
  • For tunnel-based, the default, if `accountId` is defined, and matches the account of the `userToken` defined in the file.
  • For ingress-based, if the `hosts` array contains at least one entry that is a valid URL (successful HTTP GET).
  • If both tunnel-based and ingress-based access modes are disabled, if `runtime.ingressUrl` is defined.
gitCredentials When defined, includes a Git password either explicitly, or as a secretKeyRef, similar to userToken. The password or token has the required permissions in the Git provider.

Error: failed converting helm release to GitOops;...ISC repo not initialized

This error appears when you try to Configure the Runtime as Argo CD Application in the Runtime Installation wizard.

Possible cause

The Shared Configuration Repository (ISC) has been created but is not yet initialized.

Resolution

Wait a few seconds, and try again.

Runtime timeout errors

One of these errors appear in the UI indicating a timeout after completing Runtime installation and configuration in the Runtime Installation wizard:

  • Error: "unable to initialize Codefresh Client", "error": "secrets \"codefresh-token\" not found"
  • For tunnel-based access mode, the codefresh-tunnel-client pod fails after installation.
  • Pods failed error

Possible cause

The Runtime installed successfully, but the Application Proxy (cap-app-proxy) pod is not running.
This status persists for the duration that the resources necessary for App Proxy are being created and initialized.

Resolution

Check Application Proxy (cap-app-proxy) pod status
  1. Verify the status of the cap-app-proxy pod: kubectl get pods
  2. If the pod is still Pending, check for resource constraints.
  3. Scale up your cluster if needed.

Add/update –wait flag in Install Runtime command

The --wait flag in Install Runtime command controls how long the installation process waits for pods to become ready before timing out.

  • Do one of the following:
    • If already defined, increase the timeout beyond the default 5 minutes.
    • If not defined, add the --wait flag to allow time for the pods to initialize.
      Example: --wait 10m

Invalid Git token error

This error appears in the UI after Runtime installation when all Runtime components including the Application Proxy (app-proxy) are up and running.

Possible cause

Your token is invalid because of missing scopes
OR
You are using a fine-grained token or one with custom scopes

Resolution

Check token scopes
  1. Check the scopes for the Runtime token you provided during installation. If you provided the same token as both the Runtime and user token, make sure the token has the additional scopes required.
  2. If needed, generate a new PAT (Personal Access Token) with the correct scopes.

GitHub Git Runtime token

Type Required scopes
Classic
  • repo
  • admin:repo_hook
Fine-grained (personal or group-based)
  • Repository access: All repositories or Only select repositories including all repos that Argo CD syncs from
  • Repository permissions:
    • Administration: Read and write
    • Commit statuses: Read and write
    • Contents: Read and write
    • Metadata: Read-only
    • Pull requests: Read and write
    • Webhooks: Read and write


GitHub Git user token

Type Required scopes
Classic
  • repo
  • admin:repo_hook
Fine-grained (personal or group-based)
  • Repository access: All repositories or Only select repositories including all repos that Argo CD syncs from
  • Repository permissions:
    • Administration: Read and write
    • Commit statuses: Read and write
    • Contents: Read and write
    • Metadata: Read-only
    • Pull requests: Read and write
    • Webhooks: Read and write
Skip validation for fine-grained GitHub tokens

If using a custom-scope or fine-grained token and your Runtime version is v0.18.0 or lower, you must disable token validation to prevent failures.

  1. Check Runtime version:
    • In the Codefresh UI, on the toolbar, click the Settings icon.
    • From the sidebar, select GitOps Runtimes.
    • In the Versionw column, if the chart version is v0.18.0 or lower, continue with step 2.
  2. Add the skipGitPermissionValidation flag to your values.yaml file:
app-proxy:
  config:
    skipGitPermissionValidation: "true"

Could not connect to Argo CD error (Existing Argo only)

When you try to Configure the Runtime as an Argo CD Application, the Runtime tries to connect to the Argo CD instance.

Possible cause

The Runtime cannot connect to the Argo CD instance due to one of these reasons:

  • The Runtime is not installed in the same namespace as Argo CD
  • The Runtime cannot reach required services: argocd-server, argocd-repo-server, argocd-redis.
  • Your Argo CD instance uses a non-default root path behind a reverse proxy.

Resolution

Follow the steps in the order in which they are listed.

1. Check Runtime namespace

Check the namespace where the Runtime is installed. It must match the Argo CD namespace.

2. Check service labels if using auto-detection
  1. If you have configured auto-detect for Argo CD services, check if the labels are correctly defined:
    • argocd-server: app.kubernetes.io/component=server,app.kubernetes.io/part-of=argocd
    • argocd-repo-server: app.kubernetes.io/component=repo-server,app.kubernetes.io/part-of=argocd
    • argocd-redis: app.kubernetes.io/component=redis,app.kubernetes.io/part-of=argocd
3. Manually configure service names and ports in values.yaml
  • If labels are not correctly defined, or if you are not using auto-detect, define service names and ports in the values.yaml file:
global:
  external-argo-cd:
    server:
      svc: argocd
      port: 80
    redis:
      svc: argocd-redis
      port: 6379
    repoServer:
      svc: argocd-repo-server
      port: 8081
...
4. Verify Argo CD root path configuration
  • If your Argo CD instance is behind a reverse proxy and uses a non-default root path, configure the path in values.yaml:
global:
  external-argo-cd:
    server:
      svc: argocd
      port: 80
      rootpath: '/argocd' # example value if ArgoCD is behind a reverse proxy such as https://example.com/argocd/
...

Install GitOps Runtime with existing Argo CD
Install GitOps Runtime with new Argo CD