Evidence sources: Git, Jira, docs, deployment
Horologium's Product Truth is only as complete as the evidence feeding it. In
the target architecture, four kinds of source feed evidence into the Rust
core through the same provider contract (docs/adr/0011-evidence-provider-contract-and-provenance.md):
| Source class | What it's authoritative for | Trust tier |
|---|---|---|
Git (vcs) | Commit ancestry, tag containment, file contents at a commit | system_of_record |
Jira (tracker) | Issue status, fields, and explicit ticket-key references | system_of_record for structured fields |
Documentation (documentation) | Prose describing product behavior | asserted — a docs page states something without being the authority on whether it's still true |
Deployment records (deployment) | What release is running on what target, over what interval | system_of_record |
Every provider implements one shared trait (EvidenceProvider) and can only
ever emit evidence — never a claim or a finding directly. That boundary is
enforced by the type system, not by convention: the batch type a provider
returns has no variant for anything except an immutable evidence item with a
re-fetchable citation. See Integrity states and the
evidence model for what happens to evidence
once it's collected.
Every outbound request any provider makes goes through one shared, egress- controlled HTTP client: HTTPS-only by default, an explicit host allowlist with no default wildcard, DNS-resolution checks against private/link-local ranges on every request and every redirect, and a hard cap on redirects and response size. An unconfigured provider fetches nothing — see Security, privacy and data boundaries for the full egress and credential model.
What's actually wired up for operators today
Being direct about the current state matters more here than anywhere else in
this documentation set. Git, Jira, docs, and deployment providers exist as
Rust implementations and are exercised end-to-end in this repository's test
suite (crates/horologium-providers, crates/horologium-providers-conformance)
against the same golden fixture the hosted demo runs. What
does not exist yet in this Public Alpha slice is an operator-facing
collection CLI or a .env/config-file surface for pointing a live instance at
your own Git remote, Jira project, or docs site and running a real collection.
In concrete terms, as a self-host operator today you can:
- Run
horologium-serverand see the dashboard and API against whatever is already in the database — currently, that means the golden fixture seeder (seed_golden_fixture, see the self-host quickstart), not a live pull from your own systems. - Read the full evidence/claim/finding model this repository implements, and
verify it against
docs/adr/0011-evidence-provider-contract-and-provenance.mdand the ontology document, both in the repository.
Wiring a live collection run against a real Git remote, Jira project, or docs
site — with real credentials via credential_ref, a real
egress.allowed_hosts allowlist, and a real schedule — is scoped ahead of
this ticket and tracked separately. This is named explicitly in
Public Alpha limitations rather than left as a
gap you discover mid-setup.
Credential handling, as designed
Whenever provider configuration does land, the documented shape is already fixed by ADR-0015 and worth knowing in advance:
- Configuration stores a
credential_ref— the name of an environment variable or a file path — never a credential value. The core resolves it at process start. - Credentials are never logged, never included in an error message, never returned by any endpoint, and never written to evidence.
- Least privilege is the documented requirement: read-only tokens, scoped to the specific repository, project, or docs space you're connecting — never a broad admin token.
See Security, privacy and data boundaries for the complete model.