Argo CD

HealOps queries the Argo CD REST API as a read-only evidence source during GitOps incident investigations. It can list visible applications, inspect one application’s sync and health status, and fetch sanitized server-side diff output to show deployment drift.

Prerequisites

Argo CD API server reachable from the machine running HealOps
A dedicated Argo CD account or API token with read access to the applications you want HealOps to inspect
The Argo CD base URL, for example https://argocd.example.com
Optional alert annotations that identify the affected Argo CD application, project, namespace, or revision

Setup

Argo CD is configured through environment variables or the persistent integration store.

Option 1: Environment variables

Add one authentication method to your .env:

ARGOCD_BASE_URL=https://argocd.example.com

# Option A: API token auth. The token may be set with or without a "Bearer " prefix.
ARGOCD_AUTH_TOKEN=***
# ARGOCD_TOKEN=***   # alias also supported

# Option B: username/password auth. Use instead of ARGOCD_AUTH_TOKEN.
# ARGOCD_USERNAME=healops-readonly
# ARGOCD_PASSWORD=***

# Optional scoping and TLS settings
ARGOCD_PROJECT=default
ARGOCD_APP_NAMESPACE=argocd
ARGOCD_VERIFY_SSL=true

Variable	Default	Description
`ARGOCD_BASE_URL`	—	Required. Argo CD API base URL. Remote URLs must use `https://`; plain `http://` is accepted only for loopback or localhost development URLs.
`ARGOCD_AUTH_TOKEN`	—	Argo CD bearer/API token. Use this or username/password, not both.
`ARGOCD_TOKEN`	—	Alias for `ARGOCD_AUTH_TOKEN`.
`ARGOCD_USERNAME`	—	Username for Argo CD session login. Use together with `ARGOCD_PASSWORD`.
`ARGOCD_PASSWORD`	—	Password for Argo CD session login. Use together with `ARGOCD_USERNAME`.
`ARGOCD_PROJECT`	—	Optional Argo CD project filter for listing and application-specific requests.
`ARGOCD_APP_NAMESPACE`	—	Optional application namespace passed as `appNamespace` for application-specific requests.
`ARGOCD_VERIFY_SSL`	`true`	Whether to verify TLS certificates. Set to `false` only for trusted local or lab environments.

HealOps rejects ambiguous auth configuration. Do not set a bearer token and username/password at the same time.

Option 2: Persistent store

You can also add Argo CD to ~/.config/healops/integrations.json:

{
  "version": 1,
  "integrations": [
    {
      "id": "argocd-prod",
      "service": "argocd",
      "status": "active",
      "credentials": {
        "base_url": "https://argocd.example.com",
        "bearer_token": "***",
        "project": "default",
        "app_namespace": "argocd",
        "verify_ssl": true
      }
    }
  ]
}

The store also accepts auth_token or token as aliases for bearer_token. For username/password auth, omit bearer_token and set username and password instead.

Option 3: Multiple Argo CD instances

For multiple Argo CD instances, set ARGOCD_INSTANCES to a JSON array. The first valid instance is used as the default integration for investigations.

export ARGOCD_INSTANCES='[
  {
    "name": "prod",
    "tags": {"env": "prod"},
    "credentials": {
      "base_url": "https://argocd.prod.example.com",
      "bearer_token": "***",
      "project": "default"
    }
  },
  {
    "name": "staging",
    "tags": {"env": "staging"},
    "base_url": "https://argocd.staging.example.com",
    "username": "healops-readonly",
    "password": "***"
  }
]'

When ARGOCD_INSTANCES is set, the single-instance ARGOCD_BASE_URL and auth variables are ignored for this service. healops integrations verify argocd validates the resolved default instance.

Verify

Run:

healops integrations verify argocd

Expected output:

Service: argocd
Status:  passed
Detail:  Connected to Argo CD and listed 3 applications.

Verification performs a read-only application list call. It proves HealOps can reach Argo CD and list visible applications with the configured credentials; it does not write to Argo CD or sync applications.

Usage in investigations

When Argo CD is configured and an incoming alert contains GitOps context, HealOps can add Argo CD evidence to the investigation plan. HealOps recognizes these explicit alert fields:

Field	Location	Purpose
`argocd_application` or `argocd_app`	Top-level alert payload or `annotations`	Name of the affected Argo CD application.
`application_name`	`annotations`	Generic application name fallback.
`argocd_revision`	Top-level alert payload or `annotations`	Revision mentioned by the alert.
`revision`	`annotations`	Generic revision fallback.
`argocd_project`	Top-level alert payload or `annotations`	Argo CD project for scoped application requests.
`argocd_app_namespace`	Top-level alert payload or `annotations`	Argo CD application namespace for scoped requests.

HealOps also looks for GitOps hints in alert text such as argocd, argo cd, argo-cd, gitops, outofsync, or outofsynced. Example alert:

{
  "alert_name": "checkout-api OutOfSync",
  "annotations": {
    "summary": "Argo CD reports checkout-api is OutOfSync",
    "argocd_application": "checkout-api",
    "argocd_project": "default",
    "argocd_revision": "abc123"
  }
}

Then run HealOps with the alert payload:

healops investigate -i alert.json

Evidence collected

`argocd_application_status`

Fetches application status from Argo CD.

With application_name, it returns a compact summary for that application: sync status, health status, current revision, operation phase/message, destination, images, and recent deployment history.
Without application_name, it lists visible applications, optionally scoped by ARGOCD_PROJECT.

The investigation agent uses this evidence to determine whether a deployment is OutOfSync, Degraded, on an unexpected revision, or correlated with a recent rollout.

`argocd_application_diff`

Fetches Argo CD server-side diff output for one application.

Requires application_name.
Returns drift_detected, diff_count, and sanitized diff records.
Helps identify Kubernetes objects whose live state differs from the desired GitOps state.

Security best practices

Use a dedicated read-only Argo CD account or token for HealOps.
Store credentials in .env or ~/.config/healops/integrations.json, not in source code.
Use https:// for remote Argo CD URLs. Plain http:// is accepted only for loopback or localhost development URLs.
Do not disable ARGOCD_VERIFY_SSL for production instances.
HealOps redacts bearer tokens, passwords, token-like strings, and Kubernetes Secret diffs before surfacing Argo CD errors or diff evidence.
The integration is read-only: it lists applications, reads application summaries, and reads server-side diff data. It does not sync, modify, or delete Argo CD resources.

Troubleshooting

Symptom	Fix
Status: missing	Set `ARGOCD_BASE_URL` and exactly one auth method, or add an active `argocd` store entry.
Remote `http://` URL rejected	Use `https://` for remote Argo CD. Use plain HTTP only for `localhost`, `127.0.0.1`, or `::1` development endpoints.
401 Unauthorized	Check the token, or verify that username/password login can create an Argo CD session.
403 Forbidden	Ensure the account can list applications and read the target application.
SSL error	Fix the certificate chain or, for a trusted lab only, set `ARGOCD_VERIFY_SSL=false`.
No diff evidence	Confirm the alert provides `argocd_application` or `argocd_app`; the diff tool requires an application name.
Application list succeeds but a named app fails	Check `ARGOCD_PROJECT` and `ARGOCD_APP_NAMESPACE`, and confirm the account has access to that application.

Overview

LLM providers

Observability and incidents

Cloud, code, and collaboration

Messaging

Data and workflow systems

Prerequisites

Setup

Option 1: Environment variables

Option 2: Persistent store

Option 3: Multiple Argo CD instances

Verify

Usage in investigations

Evidence collected

`argocd_application_status`

`argocd_application_diff`

Security best practices

Troubleshooting

​Prerequisites

​Setup

​Option 1: Environment variables

​Option 2: Persistent store

​Option 3: Multiple Argo CD instances

​Verify

​Usage in investigations

​Evidence collected

​argocd_application_status

​argocd_application_diff

​Security best practices

​Troubleshooting

Prerequisites

Setup

Option 1: Environment variables

Option 2: Persistent store

Option 3: Multiple Argo CD instances

Verify

Usage in investigations

Evidence collected

`argocd_application_status`

`argocd_application_diff`

Security best practices

Troubleshooting