assent

module

v0.3.0 Latest Latest Go to latest Published: Aug 18, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/PlatformRelay/assent

Links

Open Source Insights

README ¶

Deterministic, policy-driven auto-merge for self-service repos

Canonical repo: GitHub (PlatformRelay/assent). Status: alpha — the GitLab CI path is Core (E2–E8 engine, forge, provider, renderer). Pre-1.0: policy schema and CLI flags may change between releases; see API stability.

assent is a deterministic, policy-driven auto-merge gate for self-service configuration repositories. Drop it into a repo's CI pipeline and it turns merge requests into decisions: approve, comment, request changes, or block — based on rules you write in Kyverno-style declarative YAML with CEL predicates.

Read the docs: platformrelay.github.io/Assent — vision, architecture, ADRs, install guide, and usage walkthrough. This README is the front door; the site is the map.

Why

Most changes to config repos (topic definitions, service catalogs, tfvars, tenant onboarding files) are routine: a team edits their own entries within safe bounds. Yet a human still has to review every MR, reconstructing the same context each time — what changed, who owns it, is it destructive, which policy applies. assent encodes that reasoning as policy so the routine 90% merges itself and reviewers spend their attention on the risky 10%.

Fail-safe decisions — every run emits an auditable DecisionRecord; ambiguous policy fails closed (ADR-0015).
Semantic diffs — JSON, YAML, and HCL/tfvars parse into field-level adds/modifies/deletes, not line noise (ADR-0003).
Testable policies — fixture changes in, expected decision out; policies without tests are a lint error (ADR-0014).

How it works

flowchart LR
  MR["Merge request"] --> CI["GitLab CI job"]
  CI --> Assent["assent run"]
  Assent --> Forge["GitLab forge API"]
  Assent --> Providers["Permission & fact providers"]
  Assent --> Policy[".assent/ policies"]
  Assent --> Out["Threads · comments · approve · merge"]

Key property: assent is stateless per invocation — every run recomputes the decision from (diff, repo snapshot, facts, policy version). No database, no long-lived service in v1. See system context for the full C4 diagram.

Quick start

Install from source (install guide):

go install github.com/PlatformRelay/assent/cmd/assent@latest
assent version

go install compiles without link-time stamping, so the binary it produces reports assent 0.0.0-dev — even when you pin a tag (@v0.1.0). For a version-stamped binary take the Homebrew tap or a release archive: goreleaser injects the version (-X main.version) and the archives are checksum- and signature-verifiable. Both routes are in docs/usage/install.md.

Lint and test policies locally. Both commands take the repository root — assent appends .assent itself, so passing .assent/ makes it look for .assent/.assent:

assent lint .
assent test .

No repo of your own yet? A clone of this one ships runnable sample policy trees; run the two commands above from examples/packs/service-catalog (that is the fixture hack/docs/readme_smoke_test.sh executes this block against).

Developers: gates live in the Taskfile:

task check   # fmt + vet + lint + test

Feature maturity

Honest tiers post-E8 (D-104). Core = shipped and covered by conformance tests; Planned = designed seam, not yet implemented; Locked = deferred epic; Designed = ADR/spec only.

Area	Status	Notes
Policy lint / test	Core	`assent lint`, `assent test`, schema drift gates
GitLab forge	Core	Snapshot, resolve, reconcile, merge CAS
Provider builtins	Core	GitLab groups, ownership file, static facts
Renderer	Core	Finding threads, summaries, presentation lint
GitHub adapter	Planned	E10 — designed seam (D-012)
Rego backend	Locked	E11 — CEL/assert path is Core today
`serve` (HTTP API)	Designed	E12 — CLI-only in v1
Remote packs	Locked	E13 — local `.assent/` only

Learn more

Topic	Link
Documentation site	platformrelay.github.io/Assent
Install (go, curl, Homebrew)	usage/install.md
API & schema stability	API_STABILITY.md
Security policy & CI gates	SECURITY.md
Vision & personas	docs/vision.md
Architecture (C4)	docs/architecture/
Decision log	docs/decisions/decisions.md

Repository layout

Path	Purpose
`docs/`	Product docs (published via MkDocs)
`docs/planning/`	Contributor planning notes (not in published nav)
`openspec/`	Spec-driven development specs and change proposals
`cmd/assent/`	CLI entry point
`internal/`	Go packages (hexagonal: core + ports + adapters)
`examples/`	Sample policies and self-service repo layouts
`test/e2e/`	End-to-end strategy: kind-hosted GitLab / testcontainers
`hack/release/`	Snapshot builds, install script, release verify harness

License

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
assent command Command assent is the CLI entry point for the deterministic auto-merge gate.	Command assent is the CLI entry point for the deterministic auto-merge gate.
hack
spikes/cel Package celspike is a throwaway Spike A harness for CEL residual risks (ADR-0013).	Package celspike is a throwaway Spike A harness for CEL residual risks (ADR-0013).
spikes/provider Package provider is Spike C (P2-E3): a throwaway proof of the typed, minimized HTTP/exec provider contract (ADR-0017 §6) and the token-isolation invariant (ADR-0015 §7).	Package provider is Spike C (P2-E3): a throwaway proof of the typed, minimized HTTP/exec provider contract (ADR-0017 §6) and the token-isolation invariant (ADR-0015 §7).
spikes/provider/maliciousexec command Command maliciousexec is a deliberately hostile exec provider for the isolation spike: it exfiltrates everything it can see — its entire environment and its full stdin — to stdout.	Command maliciousexec is a deliberately hostile exec provider for the isolation spike: it exfiltrates everything it can see — its entire environment and its full stdin — to stdout.
spikes/provider/toyexec command Command toyexec is the exec transport of the toy group-membership provider: FactQuery on stdin, FactResponse on stdout.	Command toyexec is the exec transport of the toy group-membership provider: FactQuery on stdin, FactResponse on stdout.
internal
adoptertest Package adoptertest is the PURE library behind `assent test` (P5-E6).	Package adoptertest is the PURE library behind `assent test` (P5-E6).
catalogue Package catalogue is assent's pure generated rule catalogue (D-017 B10).	Package catalogue is assent's pure generated rule catalogue (D-017 B10).
change Package change implements assent's canonical change model: it diffs a base and head version of a single file into a byte-stable ChangeSet that predicates evaluate over (ADR-0003, ADR-0011).	Package change implements assent's canonical change model: it diffs a base and head version of a single file into a byte-stable ChangeSet that predicates evaluate over (ADR-0003, ADR-0011).
compare Package compare is the PURE promotion-comparison engine behind `assent compare` (P5-E6-S09 seed, PCS epic extensions).	Package compare is the PURE promotion-comparison engine behind `assent compare` (P5-E6-S09 seed, PCS epic extensions).
core/aggregate Package aggregate is the PURE, order-independent obligations aggregator for the P4-E1 walking skeleton (P4-E1-S03, ADR-0017 §2/§6).	Package aggregate is the PURE, order-independent obligations aggregator for the P4-E1 walking skeleton (P4-E1-S03, ADR-0017 §2/§6).
core/classify Package classify is the PURE, minimal change-classifier for the P4-E1 walking skeleton (P4-E1-S07-01, ADR-0008 §1, ADR-0015 §1).	Package classify is the PURE, minimal change-classifier for the P4-E1 walking skeleton (P4-E1-S07-01, ADR-0008 §1, ADR-0015 §1).
core/decision Package decision is the PURE serializer for the P4-E1 walking skeleton (P4-E1-S04, ADR-0016 §3, ADR-0017 §1/§9).	Package decision is the PURE serializer for the P4-E1 walking skeleton (P4-E1-S04, ADR-0016 §3, ADR-0017 §1/§9).
core/hash Package hash provides schema-version domain-separated digests over canonical JSON.	Package hash provides schema-version domain-separated digests over canonical JSON.
core/policy Package policy loads assent's frozen authored contracts — MergePolicy, RulesetBinding, Config, and Pack (schemas/policy/v1alpha1/**) — into engine types under strict decode, replacing the P4-E1 toy YAML (cmd/assent/policy.go).	Package policy loads assent's frozen authored contracts — MergePolicy, RulesetBinding, Config, and Pack (schemas/policy/v1alpha1/**) — into engine types under strict decode, replacing the P4-E1 toy YAML (cmd/assent/policy.go).
evaldecode Package evaldecode is the E2-S04 REQ-06 boundary that turns the LIVE differ's output into the engine's typed EvaluationInput.	Package evaldecode is the E2-S04 REQ-06 boundary that turns the LIVE differ's output into the engine's typed EvaluationInput.
forge Package forge is the ADR-0017 §7 forge port surface:	Package forge is the ADR-0017 §7 forge port surface:
forge/conformance Package conformance holds L2 conformance goldens for the forge port (ADR-0005).	Package conformance holds L2 conformance goldens for the forge port (ADR-0005).
forge/fake Package fake is the in-memory forge substrate for the P4-E1 Reconcile tests (S06/S08/S07-02).	Package fake is the in-memory forge substrate for the P4-E1 Reconcile tests (S06/S08/S07-02).
forge/gitlab Package gitlab is the REAL GitLab REST v4 adapter for the P4-E1 walking skeleton (P4-E1-S10).	Package gitlab is the REAL GitLab REST v4 adapter for the P4-E1 walking skeleton (P4-E1-S10).
glob Package glob is the single, pure path/pointer glob matcher shared by the routing classifier (internal/core/classify) and the obligation-coverage loop (internal/core/aggregate).	Package glob is the single, pure path/pointer glob matcher shared by the routing classifier (internal/core/classify) and the obligation-coverage loop (internal/core/aggregate).
lint Package lint is assent's pure `assent lint` check library over the `.assent/**` authoring surface.	Package lint is assent's pure `assent lint` check library over the `.assent/**` authoring surface.
provider Package provider hosts the typed provider protocol (ADR-0017 §6).	Package provider hosts the typed provider protocol (ADR-0017 §6).
provider/builtin Package builtin registers hermetic Phase-5 provider fact sources (forge groups, repo-file walk).	Package builtin registers hermetic Phase-5 provider fact sources (forge groups, repo-file walk).
render Package render is the pure presentation layer for assent (P5-E8, ADR-0016).	Package render is the pure presentation layer for assent (P5-E8, ADR-0016).
render/locale Package locale ships fixed renderer chrome strings keyed by stable ids (ADR-0016 §5).	Package locale ships fixed renderer chrome strings keyed by stable ids (ADR-0016 §5).
schemadrift Package schemadrift helpers verify git-tracked schema changes stay within allowed epic fences: the E8 D-088 presentation block in config.schema.json, and the D-120 toolDigest description annotation in decision-record.schema.json.	Package schemadrift helpers verify git-tracked schema changes stay within allowed epic fences: the E8 D-088 presentation block in config.schema.json, and the D-120 toolDigest description annotation in decision-record.schema.json.
schemas Package schemas compiles and validates the versioned JSON Schemas that are assent's public contract surface (ADR-0017 §7: the serialized schemas are the API, not the internal Go types).	Package schemas compiles and validates the versioned JSON Schemas that are assent's public contract surface (ADR-0017 §7: the serialized schemas are the API, not the internal Go types).
test
e2e Package e2e holds the L3 real-forge end-to-end tests, all gated behind the `e2e` build tag (see skeleton_test.go and test/e2e/README.md).	Package e2e holds the L3 real-forge end-to-end tests, all gated behind the `e2e` build tag (see skeleton_test.go and test/e2e/README.md).