Skip to main content

gtmharness

CI PyPI License: MIT

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 — plan shows 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 --verify proves 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; revert restores

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.00 aborts 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)

Source distribution for gtmharness 0.5.0
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)

Table of built distributions (wheels) for gtmharness 0.5.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.5.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page