Release Automation

Referenta release notes are generated from the GitHub release process, not from manually edited dashboard content.

Trigger

The release automation lives in .github/workflows/ci.yml and only runs when all of the following are true:

• the event is a pull request,
• the pull request is closed,
• the pull request was merged, and
• the base branch is main.

This means the release flow is tied to the promotion step into production rather than to everyday feature branches.

Title And Description Rules

For the release job to create a version tag, the merged PR title must match one of these formats:

Release Candidate: vX.Y.Z
Release: vX.Y.Z

The workflow extracts the version directly from the title. The pull request body becomes the GitHub Release description.

Operationally, that makes the PR itself the release handoff artifact:

• the title defines the version number,
• the description defines the public release content, and
• the merge into main triggers the publication step.

What The Workflow Creates

When the title matches and the PR is merged into main, the workflow:

1. checks out the repo with tag push permissions,
2. extracts the version from the PR title,
3. creates an annotated git tag on the merge commit if the tag does not already exist, and
4. creates a GitHub Release whose title is the version and whose notes come from the PR body.

This keeps releases traceable to the exact merge commit and avoids manually creating production tags outside the CI flow.

How The Dashboard Uses Release Data

The Referenta dashboard reads release information directly from GitHub:

• getGithubReleasePayload fetches release and tag data from the repository,
• /release-notes renders that data through ReleaseNotesView,
• the page body is taken from the GitHub Release description, and
• the sidebar version badge uses /api/v1/github/latest-tag together with useGithubTag.

In product terms, GitHub Releases are the content source for the dashboard's release communication. Updating a GitHub Release updates what the dashboard can display.

Freshness Model

The dashboard behavior is automatic, but it is not true push-based realtime.

The current implementation uses cached fetches and revalidation:

• the release API route is revalidated on a timed cache window,
• the latest-tag API response is cached server-side, and
• the client hook stores the latest tag in session storage for the current browser session.

So release updates propagate automatically on subsequent fetches and refreshes, but not through a live websocket-style broadcast channel.

Practical Release Flow

The expected release workflow is:

1. validate changes on dev,
2. open a PR from dev to main,
3. title it Release Candidate: vX.Y.Z or Release: vX.Y.Z,
4. write the release notes in the PR body,
5. merge the PR, and
6. let GitHub Actions create the tag and GitHub Release that the dashboard consumes.

That gives Referenta one release source of truth and keeps versioning, release notes, and dashboard display aligned.