Releases

Releases group one or more PRDs into a shippable unit. They provide the execution scope — all stories in linked PRDs execute together under one coordinator. When all stories are merged, the release executes directly as its own job to run the checkpoint pipeline (audit, release notes, tagging).

Creating a Release

  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
    • PRDs — optionally link PRDs at creation time
  4. Click Create

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.

Linking PRDs

Each release must have at least one linked PRD. PRDs provide the stories that make up the release.

  • Open a release and use the PRD Linker to add or remove PRDs
  • Each PRD can only belong to one active release at a time
  • When you link a PRD whose stories depend on stories in another release's PRDs, 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 release selection is saved per-device so it persists between sessions.

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
  • PRD Linker — add or remove linked PRDs
  • 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:

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

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.