Releases

Releases group one or more PRDs into a shippable unit. They are Trinity's primary user-facing unit — dashboard, stories list, story detail, and Architect are all scoped by active release. Every PRD belongs to exactly one release (the assignment is set when Architect saves the PRD; you can move a PRD to a different unshipped release later). When all stories under a release are merged, the release executes directly as its own job to run the release pipeline (audit, release notes, tagging).

Creating a Release

Trinity auto-creates your first release when you create your first PRD in Architect (default v0.1.0 — adjust via project settings). You rarely need to create releases by hand.

When you do want a new one (for example to plan v0.3 alongside an in-progress v0.2):

  1. Click Releases in the sidebar
  2. Click Create Release
  3. Fill in:
    • Name — a label for this release (e.g., "MVP", "Beta 2")
    • Version — the semver version (e.g., "v1.0", "v0.2")
    • Description — optional summary of what's included
  4. Click Create

Empty releases are fine — you can assign PRDs to them later from Architect or by moving existing PRDs.

Versioning Configuration

Each project has configurable versioning:

  • Tag template — the pattern for git tags (default: v{major}.{minor}.{patch}). Supports arbitrary formats like release-{major}.{minor} or {major}.{minor}.{patch}-rc.
  • Bump strategy — which semver component to auto-increment: major, minor (default), or patch.

When a release finishes, Trinity scans existing tags in each repo, parses them using the template, and auto-increments the configured component.

Release Lifecycle

Releases progress through these statuses:

Status Meaning
Created Empty release — no stories merged yet
In Progress At least one story has merged into the release branch; more work still pending
Ready Every story under every PRD in the release is merged or skipped
Staging In Progress Staging walk running — each repo's chain (default dev → staging) is being walked from the release branch
Staged Every repo's staging chain is up-to-date and verified on the preview deploy
Staging Failed One or more repos failed mid-walk; the rest may have made it through
Partially Staged Walk completed but some repos remain behind; surfaced as a recoverable state
Releasing Release pipeline running (preflight, SEO audit/fix, release notes, tagging)
Partially Released Some repos tagged, others failed (transient — the coordinator auto-retries up to three times)
Released Done — repos tagged on the production branch, release notes published

The forward happy path is created → in_progress → ready → staging_in_progress → staged → releasing → released. Reverse and side paths:

  • Yank Back (staged → ready) — undoes a staging deploy. Resets each repo's staging-chain tips to the snapshot taken when the release first reached staged, force-pushes the reset, and reopens the release so stories can resume.
  • Stop (releasing → ready) — halts the release pipeline mid-flight when something needs adjusting.
  • Retry Failed Repos (staging_failed | partially_staged → staging_in_progress) — re-runs the staging walk only for repos that didn't make it through.

Transitions are wired to specific buttons in the release detail panel — see Release Detail Panel below. The Releases page lays the main columns out as Not Started / In Progress / Ready to Release / Releasing / Released; the staging-family statuses (staging_in_progress, staged, staging_failed, partially_staged) all surface inside the Ready to Release column with their own state badge.

Recovering from a Bad Staging Deploy

When something breaks on the staging deploy and you need to back out:

  1. Open the release detail panel — it shows the Staging Drift tile and the per-repo state table
  2. Click Yank Back — Trinity force-resets each repo's staging-chain tips to the snapshot it took at staged
  3. The release returns to ready and any in-flight stories on top of the yank resume normally

Use Yank Back when the deploy itself is bad (a broken build hit staging, smoke tests fail on the preview, a regression slipped through). Use Retry Failed Repos when the walk itself errored (network timeout, transient permission issue) and the staging tips are still in a sane state.

Recovering from Partial Releases

If tagging fails for some repos during the release process, the release lands in Partially Released and the detail panel shows which repos got tagged and which failed. The coordinator auto-retries up to three times (releases.auto_retry_count); if that doesn't clear it:

  1. Open the release detail panel — it lists every repo with its tag status
  2. Click Retry Failed Repos to re-attempt tagging the remaining repos
  3. When all repos succeed, the release transitions to Released

Assigning, Moving, and Reparenting PRDs

Every PRD belongs to exactly one release, chosen when the PRD is first saved in Architect. You don't link PRDs manually — Architect suggests a target release (existing unshipped or brand new) and you confirm or override in the preview step.

Two actions on each PRD row in the release detail panel let you change that assignment afterwards:

  • Move — reassigns the PRD (and every story under it) to a different unshipped release. Use this when you want stories to ship with a different release entirely.
  • Reparent — changes the parent release without moving the PRD's stories. Use this when the structure of the parent release changed (e.g. a different release became the right home for the work that's already in flight). Only available while the target release is created or in_progress.

To move a PRD:

  1. Open the release that currently owns the PRD
  2. Click the Move action next to the PRD row
  3. Pick the target release (another unshipped release, or create a new one inline)
  4. Confirm

When a move is blocked: the Move action is disabled when the PRD has any non-terminal work — a story that's claimed, running, waiting at a gate, failed, or completed-but-not-merged. Moving would orphan live feature/release branches. Either let the in-flight stories finish or cancel/skip them first. Also: neither the source nor the target release can be past in_progress (any staged-family or shipping status freezes the release).

When a PRD whose stories depend on stories in another release's PRDs is created or moved, Trinity automatically adds a release dependency.

Release Dependencies

Releases can depend on other releases. This creates a DAG (directed acyclic graph) that enforces ordering:

  • A release cannot transition to Releasing until all its dependencies are Released
  • Dependencies are auto-inferred from cross-PRD story dependencies when linking PRDs
  • You can also add or remove dependencies manually via the Dependency Editor in the release detail panel
  • Circular dependencies are detected and blocked

Dependency Editor

Open a release and click the Dependency Editor to manage dependencies:

  1. Add a dependency — select another release from the dropdown. The current release will not be allowed to enter the "Releasing" state until the selected dependency is "Released".
  2. Remove a dependency — click the remove button next to an existing dependency to unlink it.

All dependency changes are audit-logged with the release names and versions for traceability.

Running a Release

Execution is release-scoped. To start:

  1. Go to the Run page
  2. Select the release to execute
  3. Click Run and configure workers, mode, etc.

Each release gets its own coordinator, worker pool, and job queue. You can run multiple releases in parallel — the Multi-Release Status bar shows pills for each running release with progress counts.

Your active release selection persists server-side (keyed by account_id + project_id), so it syncs across every device signed into your account — not just the device where you picked it.

Release Detail Panel

Click any release card to open its detail panel. What's visible depends on the release's status; the major surfaces are:

  • Status badge — current lifecycle state.
  • Story progress — bar showing merged / released count vs. total.
  • Release Dashboard — four tactical tiles sit at the top: Run Project, Run SEO, Run Audit, Generate Notes. Each runs its standalone agent against the current release worktree without advancing the lifecycle. While the release is staged, staging_failed, or partially_staged, every tile except Run Project shows a Locked badge (the staging deploy is the source of truth — re-running tactical agents at that point would diverge from what's on staging).
  • Commit row — primary lifecycle buttons. Which appear depends on status:
    • ready → Push to Staging
    • staging_in_progress → status indicator only
    • staged → Release, Yank Back
    • staging_failed / partially_staged → Retry Failed Repos, Yank Back
    • releasing → Stop
    • partially_released → Retry Failed Repos (after the coordinator's auto-retries exhaust)
  • Staging Drift tile — appears during staged-family statuses. Shows whether any repo's staging tip has moved since the release was staged. When drift is detected, a Redeploy to Staging button appears inside the tile.
  • CI on Staging tile — appears during staged-family statuses. Surfaces CI status for the staged tips so you don't have to switch to GitHub.
  • Per-Repo Status table — one row per repo with its current staging-chain tip, drift state, CI status, and release-pipeline phase. Drives the Retry Failed Repos button.
  • PRDs list — every PRD assigned to the release. Each row has a Move action (reassign to another release) and a Reparent action (change parent release without moving the PRD's stories). Both are available only while the target release is created or in_progress.
  • Dependency Editor — manage release dependencies.
  • Results tab — after release execution, shows per-repo tags, release notes, and preflight results. For partially released releases, shows which repos succeeded.
  • Delete — soft-deletes the release (disabled for released releases or those with active jobs).

When stories in linked PRDs have active execution jobs, editing is locked to prevent conflicts.

Automation Tab

Releases also have an Automation tab for per-release overrides. In addition to the standard automation settings (auto-PR, auto-merge, squash merge, etc.), releases support:

  • Auto-release to base — automatically merge the release branch to the production branch after release
  • Delete release branch — clean up the release branch after completion

Release overrides are editable only while the release is clean (no stories have started). Once any story in the release moves past pending, the effective setting is frozen and further edits are disabled. These overrides follow the same cascade as stories: Global → Team → User per-scope → Project → User per-project → Entity → Job.

Releases Page Layout

The Releases page organizes releases into columns by status:

  • Not Started — created releases (no stories merged yet)
  • In Progress — in_progress releases (at least one story merged, more pending)
  • Ready to Release — ready, staging_in_progress, staged, staging_failed, or partially_staged releases. The card carries an inner state badge so the staging-family is visually distinct from a clean ready.
  • Releasing — releasing and partially_released releases
  • Released — released releases (historical)

Deleting a Release

You can delete a release if:

  • It is not in released status (released releases are historical records)
  • No other active releases depend on it
  • It has no active execution jobs

Deletion is a soft delete — the record is preserved for audit purposes but hidden from the UI.