ReleaseGraph: Why Is This Blocked?

Explain exactly why a release is blocked using structured dependencies, risk, and approvals — not brittle rules or markdown.

Comment

Inspiration

Modern software teams rarely fail because code doesn’t work — they fail because context is missing. Over time, we noticed a recurring pattern: pipelines are green, tests pass, deployments succeed, yet teams still hesitate to ship. The real question isn’t“Did it build?” but“Is it safe to deploy right now?” That hesitation usually comes from hidden dependencies, risky configuration changes, and unclear approval status — information that lives in tickets, markdown files, or tribal knowledge. We were inspired to explore what happens when these relationships are modeled explicitly as structured content, instead of being implied in documents.

What it does

ReleaseGraph: Why Is This Blocked? answers one critical question:

Why can’t this release be deployed right now?

Instead of showing a generic status, the system explains exactly why a release is blocked by reasoning over structured relationships:

Which service the release belongs to Which upstream services it depends on Whether those services have active, non‑deployed releases Whether those releases contain high‑risk changes Whether required approvals exist

The result is a clear, human‑readable explanation and an explicit action needed (for example, “Approval required from Security Lead”). This kind of dependency‑aware reasoning is extremely difficult to build reliably with flat files or markdown.

How we built it

We used Sanity as a structured content backend to model the real entities involved in release decisions:

Services with explicit dependencies on other services Releases associated with services Changes with risk levels Approvals as first‑class, queryable documents

These entities are connected using Sanity references, allowing us to query and traverse relationships using GROQ. On the frontend, we built a lightweight Next.js application that queries Sanity and computes results directly from the content graph. The “blocked vs safe” decision is not AI‑generated text — it is deterministically derived from structured data, making it explainable and auditable. We also used an AI coding assistant with Sanity’s MCP Server to safely iterate on schema design and evolve relationships without breaking consistency.

Challenges we ran into

One of the main challenges was handling real‑world data behavior during rapid iteration:

Dealing with deleted or missing references gracefully Ensuring that the absence of approvals was interpreted correctly Managing caching behavior during demos so the UI always reflected the latest content state

These challenges reinforced the importance of defensive logic and clear data contracts when working with structured systems. We also had to resist the temptation to overbuild and instead focus on making one feature extremely clear and powerful.

Accomplishments that we're proud of

Building a dependency‑aware explanation system using only structured content Demonstrating a feature that flat files and markdown cannot easily support Keeping the reasoning transparent and explainable, without hiding logic behind AI summaries Creating a demo where changing content — not code — immediately changes system behavior

Seeing the UI flip from “blocked” to “safe” by simply adding an approval was a powerful validation of the approach.

What we learned

This project reinforced a key insight:

Structured content is not just about storage — it’s about reasoning.

When content has types, fields, and references, entire classes of features become simpler and more reliable. Instead of encoding business logic in UI conditionals, we can let relationships drive outcomes. We also learned that explainability matters. Users don’t just want to know that something is blocked — they want to know why, and what to do next.

What's next for ReleaseGraph: Why Is This Blocked?

There are many directions this approach could grow:

Visualizing dependency graphs and blast radius Adding historical views to show how release readiness changes over time Extending the model to compliance, audits, or change management workflows Applying the same structured reasoning to other domains where decisions depend on relationships

ReleaseGraph is intentionally small, but the pattern scales wherever decisions depend on relationships, not just state.

Built With

Share this project:

Updates