Skip to main content

Documentation Index

Fetch the complete documentation index at: https://opensre.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

OpenSRE 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 OpenSRE
  • A dedicated Argo CD account or API token with read access to the applications you want OpenSRE 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=opensre-readonly
# ARGOCD_PASSWORD=***

# Optional scoping and TLS settings
ARGOCD_PROJECT=default
ARGOCD_APP_NAMESPACE=argocd
ARGOCD_VERIFY_SSL=true
VariableDefaultDescription
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_SSLtrueWhether to verify TLS certificates. Set to false only for trusted local or lab environments.
OpenSRE 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 ~/.tracer/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": "opensre-readonly",
    "password": "***"
  }
]'
When ARGOCD_INSTANCES is set, the single-instance ARGOCD_BASE_URL and auth variables are ignored for this service. opensre integrations verify argocd validates the resolved default instance.

​
Verify

Run: 
opensre 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 OpenSRE 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, OpenSRE can add Argo CD evidence to the investigation plan. OpenSRE recognizes these explicit alert fields:
FieldLocationPurpose
argocd_application or argocd_appTop-level alert payload or annotationsName of the affected Argo CD application.
application_nameannotationsGeneric application name fallback.
argocd_revisionTop-level alert payload or annotationsRevision mentioned by the alert.
revisionannotationsGeneric revision fallback.
argocd_projectTop-level alert payload or annotationsArgo CD project for scoped application requests.
argocd_app_namespaceTop-level alert payload or annotationsArgo CD application namespace for scoped requests.
OpenSRE 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 OpenSRE with the alert payload: 
opensre 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 OpenSRE.
  • Store credentials in .env or ~/.tracer/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.
  • OpenSRE 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

SymptomFix
Status: missingSet ARGOCD_BASE_URL and exactly one auth method, or add an active argocd store entry.
Remote http:// URL rejectedUse https:// for remote Argo CD. Use plain HTTP only for localhost, 127.0.0.1, or ::1 development endpoints.
401 UnauthorizedCheck the token, or verify that username/password login can create an Argo CD session.
403 ForbiddenEnsure the account can list applications and read the target application.
SSL errorFix the certificate chain or, for a trusted lab only, set ARGOCD_VERIFY_SSL=false.
No diff evidenceConfirm the alert provides argocd_application or argocd_app; the diff tool requires an application name.
Application list succeeds but a named app failsCheck ARGOCD_PROJECT and ARGOCD_APP_NAMESPACE, and confirm the account has access to that application.