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 checkpoint 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 Work in progress — stories are being built
Ready All stories complete, ready for release process
Releasing Release checkpoint running (audit, notes, tagging)
Partially Released Some repos tagged, others failed (network error, permission issue)
Released Done — repos tagged, release notes published

Transition between statuses using the buttons in the release detail panel.

Recovering from Partial Releases

If tagging fails for some repos during the release process, the release enters a Partially Released state. You can retry the failed tags:

  1. Open the release detail panel — it shows which repos were tagged and which failed
  2. Click Retry Tags to attempt tagging the remaining repos
  3. If all repos are tagged successfully, the release automatically transitions to Released

This avoids having to redo the entire release process when a transient failure (e.g., network timeout) interrupts tagging.

Assigning and Moving 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.

To move a PRD to a different release later:

  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 in releasing status (shipping 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 Start 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 is persisted in the sync DB (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:

  • Status badge and transition buttons — advance through the lifecycle
  • Story progress — bar showing merged/released count vs. total
  • PRDs list — shows every PRD assigned to the release, each with a Move action for reassigning to another unshipped release
  • 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 and a Retry Tags button for failed ones.
  • 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:

  • Use release branches — overrides the project-wide toggle for this release only. Leave it unset (the default) to inherit the project setting live until the release starts running; set it explicitly to freeze the behavior regardless of later project changes.
  • Auto-release to base — automatically merge to the base 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 → Project → Entity → Job.

Releases Page Layout

The Releases page organizes releases into columns by status:

  • In Progress — created releases
  • Ready to Release — ready releases
  • Releasing — releasing 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.