Argo CD deployment-change investigation and evidence tooling for GitOps environments.
Evidra is an open-source tool developed and maintained by SameBits.
Evidra-GitOps explains what happened during a deployment and produces audit-ready evidence from Argo CD history.
It does not deploy, monitor, or alert.
It helps you understand, trace, and export production changes.
Change is the primary investigation unit in Evidra-GitOps.
A Change represents a single Argo CD deployment operation with:
- revision and source reference
- target cluster and namespace
- initiator identity
- timestamps and result
- health transitions after deploy
- attached external change / ticket annotations
- supporting evidence timeline
All search, UI, and export revolve around Change, not raw events.
Change view includes investigation trust anchors:
- visible Change Summary (what/where/who/result)
- stable permalink for shared investigation context
- observational degradation-after-deploy indicator (non-causal wording)
- evidence freshness/completeness hint
- audit-grade export metadata
- Quickstart:
docs/setup/quickstart.md - Deployment (Kustomize):
docs/setup/deployment-kustomize.md - Adoption guide:
docs/setup/adoption-guide.md - Configuration modes:
docs/setup/config-modes.md - Architecture (v0.1):
docs/architecture/architecture-v1.md - Argo evidence model:
docs/architecture/argo-evidence-model.md - Argo ingest logic (v0.1):
docs/architecture/argo-ingest-logic.md - OpenTelemetry integration:
docs/architecture/otel-integration.md - ADR: Ingestion model:
docs/adr/000X-ingestion-poll-and-watch.md - Plan: Watch backend (v0.2):
docs/architecture/ingestion-watch-plan-v0.2.md - API contracts:
docs/api/contracts-v1.md - Specs:
docs/specs/ - Argo annotations integration:
docs/integration/argo-annotations.md - Incident walkthrough (v0.1):
docs/stories/incident-walkthrough-v0.1.md - UI Explorer (v1):
docs/ui/explorer-v1.md - UI E2E testing:
docs/testing/ui-e2e.md - UI use case mapping:
docs/testing/ui-use-cases.md - Release notes (v0.1.0):
docs/release/v0.1.0.md - Release criteria:
docs/release/v0.1.0-criteria.md
Evidra-GitOps can link deployments to enterprise change management using Argo CD Application annotations:
metadata:
annotations:
evidra.rest/change-id: CHG123456
evidra.rest/ticket: JIRA-123These references appear in:
- Change view
- search results
- exported evidence
No direct ITSM or Jira integration is required in v0.1.
Argo-first, read-only evidence model
Argo CD -> ingest -> normalize -> Change timeline -> API -> Explorer UI -> export
Key principles:
- Argo CD is the single upstream signal source
- Evidence is append-only and deterministic
- UI is investigation-first, not monitoring
- Installation is lightweight and self-contained
Evidra-GitOps uses OpenTelemetry as its native observability stack for traces, metrics, and structured logging.
Spans cover the full request lifecycle: HTTP handling (otelhttp), service orchestration, change projection, Argo collector polls, evidence pack generation, and database queries (otelsql). W3C Trace Context propagation is enabled by default.
Configure via environment variables:
EVIDRA_OTEL_TRACES_EXPORTER=otlp # none | otlp | stdout
EVIDRA_OTEL_EXPORTER_ENDPOINT=localhost:4317
EVIDRA_OTEL_SAMPLER_TYPE=parentbased_traceidratio
EVIDRA_OTEL_SAMPLER_ARG=1.0
Custom application metrics are exposed at GET /metrics via the OTel Prometheus exporter. All metric names use the evidra. prefix.
| Category | Examples |
|---|---|
| Ingest | evidra.ingest.events_total, evidra.ingest.batch_size, evidra.ingest.payload_bytes |
| Argo collector | evidra.argo.polls_total, evidra.argo.events_collected_total, evidra.argo.lag_seconds |
| Changes | evidra.changes.query_duration_seconds, evidra.changes.count |
| Export | evidra.export.jobs_total, evidra.export.duration_seconds, evidra.export.artifact_bytes |
| Auth | evidra.auth.decisions_total, evidra.auth.rate_limit_hits_total |
| HTTP | Auto-instrumented by otelhttp (http.server.request.duration, http.server.active_requests) |
| Database | Auto-instrumented by otelsql (db.sql.latency, db.sql.connection.*) |
EVIDRA_OTEL_METRICS_EXPORTER=prometheus # none | prometheus
All server logs use structured JSON via go-logr/zapr (zap backend). Audit auth events include decision, mechanism, actor, and correlation IDs.
Evidra-GitOps is not:
- a CI/CD system
- a monitoring or alerting tool
- a policy or approval engine
- a generic Kubernetes event archive
- a full ITSM integration platform
Scope is intentionally narrow:
explain Argo CD production changes.
v0.1.0 — initial public release
Focus:
- Argo-first investigation workflow
- Change timeline visualization
- correlation search
- deterministic evidence export with audit metadata
- Change Summary and stable permalinks
- degradation-after-deploy observational indicator
- local and Kubernetes quickstart
Expect rapid iteration based on real user feedback.
- Docker
- kubectl
- kind
git clone https://github.com/vitas/evidra-gitops
cd evidra-gitops
cp .env.example .env
make evidra-demoRun deterministic validation cases:
make evidra-demo-testOpen Explorer:
http://localhost:8080/ui/- permalink form:
http://localhost:8080/ui/explorer/change/{change_id}
Stop demo:
make evidra-demo-cleanmake trial-apply
make trial-smokeAfter v0.1:
- richer investigation UX
- optional external adapters (Git / ITSM)
- multi-cluster aggregation
- compliance-oriented evidence reports
Contributions, issues, and investigation feedback are welcome.
Start with:
- running the quickstart
- reproducing an incident scenario
- opening an issue with findings or UX gaps
Apache License 2.0
Part of the Evidra open-source toolset by SameBits. This name is used strictly for open-source identification purposes.