gtmharness
CI/CD discipline for GTM pipelines. GTM workflows get built in no-code tools, handed over as "a Loom video and a Clay table nobody else understands," and break silently six months later when a field gets renamed upstream. gtmharness applies the engineering practices that already fixed software to GTM:
- Pipelines as code — declared in YAML, validated at load time
- Contract tests — sinks declare field contracts (required, type, picklist enum); violations block the run
- Schema drift detection — snapshot source schemas; a renamed/removed/re-typed field fails loudly instead of quietly breaking routing
- Dry-run plans —
planshows the exact write set (WRITE / BLOCK per row) before anything touches the CRM - Tamper-evident audit log — every write is logged with a rolling SHA-256 hash chain;
audit --verifyproves the log is intact - Enrichment waterfall — BYO provider keys, cost-ordered, cached (never pay for the same lead twice), budget-capped per run
- Rollback — every run snapshots its write set;
revertrestores
Built from real Reddit pain in r/gtmengineering, r/revops, and r/marketing:
"I've seen too many 'GTM OS' builds handed over as a Loom video and a Clay table nobody else understands. Six months later a field gets renamed upstream and the routing quietly breaks."
"Most attribution tools fail not because of the tool but because the underlying CRM data isn't structured to feed them."
"If it writes under the rep's name, you can't filter its changes in reports, you can't audit what it touched."
Install
pip install -e .
Quickstart
# 1. Declare a pipeline (see examples/pipeline.yaml)
# 2. Check spec + detect schema drift
gtmharness check examples/pipeline.yaml
# 3. Dry-run: see exactly what would be written
gtmharness plan examples/pipeline.yaml
# 4. Run — writes only if the plan passes; everything audited
gtmharness run examples/pipeline.yaml
# 5. Read the audit log
gtmharness audit examples/pipeline.yaml
Example plan output:
PLAN pipeline=inbound_lead_routing rows_in=3 writes=3 errors=0
[WRITE ] to_crm <- jane@acme.com {'email': 'jane@acme.com', 'lead_source': 'paid', ...}
[BLOCK ] to_crm <- bad@x.com {'email': 'bad@x.com', 'lead_source': 'free'}
! field 'lead_source': value 'free' not in enum ['paid', 'organic', 'event', 'referral']
Philosophy
- Local-first, zero-credit. The core never talks to a paid API. Bring your own provider keys via source adapters — no Clay-style credit metering.
- Fail loudly, write nothing. A blocked run writes zero rows. No partial state.
- The contract is the documentation. No Loom video required.
Enrichment waterfall — BYO keys, cost-ordered, budget-capped
- name: enrich
kind: transform
using: enrich
config:
providers: [prospeo, leadmagic] # cheapest first; falls through on miss
provider_config: {PROSPEO_API_KEY: "…", LEADMAGIC_API_KEY: "…"}
- Cost-ordered: try the cheapest provider first, fall through only on a miss
- Per-lead cache: the same lead is never purchased twice (cached per state dir)
- Budget cap:
gtmharness run pipe.yaml --budget 5.00aborts the run the moment cumulative spend crosses the cap, with a ledger summary - Every provider call is logged to the ledger with its real price
Webhook sinks
- name: fan_out
kind: sink
using: webhook
config: {url: "https://hooks.example.com/leads"}
Skills — reusable pipeline templates
gtmharness skills # list built-in + user skills
gtmharness skill inbound_lead_routing --set source_path=leads.json crm=crm
Skills are plain YAML with {{param}} slots — drop your own into
~/.gtmharness/skills/ and share them as files. No marketplace, no lock-in.
Real CRM sinks (optional extras)
pip install "gtmharness[hubspot]" # official HubSpot SDK
pip install "gtmharness[salesforce]" # simple-salesforce
Point a sink at using: hubspot or using: salesforce with your credentials in
the step config. The dry-run plan and audit log still gate every write — the
adapter is only the final "do it" step.
Provider cost ledger
gtmharness ledger
# prospeo: 14 calls, 14 rows, $0.1400
Every BYO provider call is logged with its real cost to ledger.jsonl —
total transparency about what enrichment actually costs you.
Status
v0.3.0 — spec validation, schema drift, dry-run plans, audit log, CSV/JSON sources, skills registry, HubSpot + Salesforce + webhook sink adapters, enrichment waterfall (BYO keys, cost-ordered, cached, budget-capped), provider cost ledger, GitHub Action.
Roadmap: see MILESTONES.md (M4: trust & ops — diff, doctor, rollback, tamper-evident audit log).
MIT licensed.
Metadata
Release files for gtmharness 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gtmharness-0.5.0.tar.gz | 29.1 kB | Without provenance | Details for gtmharness-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gtmharness-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for gtmharness-0.5.0-py3-none-any.whl |
Total release size: 54.7 kB
Release files / gtmharness-0.5.0.tar.gz
| Download URL | gtmharness-0.5.0.tar.gz |
|---|---|
| Size | 29.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
00d80ab409ee1040e01a3d019becd3ad157e5bde31bbd825d41e2d8c18ac66b0
|
|
BLAKE2b-256 checksum How to use checksums |
0ea720133bcb43e998260526639457966fa8e6ce49ed79e8aefc90037b2d6e58
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / gtmharness-0.5.0-py3-none-any.whl
| Download URL | gtmharness-0.5.0-py3-none-any.whl |
|---|---|
| Size | 25.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
492c71704620b153a434e3334f70bc3e1b54b0cb3c4695d896e395fdc758758d
|
|
BLAKE2b-256 checksum How to use checksums |
7c25a04a666b6a8eb8b5120b22f9d705bd0edaf5e19d439384633d188fe10ce0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for gtmharness 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.