Releases & merge-back

A release in ForgeAI is the last stage of the workflow lifecycle: it takes work that agents produced on workflow branches and folds it back into your repository's history — first by merging branches, then by tagging a version. Like everything else in ForgeAI, the git operations run on your machine through the CLI; the cockpit orchestrates the process and shows you its progress.

There are two release types:

Type	What it does
MERGE_BACK	Merges one completed workflow's branch back into the branch it was created from.
RELEASE	Merges one or more completed workflows into a dedicated release branch, then tags a semver version on your main branch.

Merge-back

Every workflow gets its own base branch (for example feature/user-auth/base). Once the workflow is done, that branch needs to return to its source branch — that is merge-back.

The cockpit offers Merge back on a workflow when all of the following are true:

• the workflow is a standard workflow with status Completed,
• all of its tasks are completed,
• its source branch is not main or develop (work branched directly off main is released instead),
• it is not already claimed by another release.

Clicking Merge back creates a MERGE_BACK release that targets the workflow's source branch. A merge task is dispatched to a connected CLI, and the agent performs the actual git merge in a local container using dedicated MCP tools (forge_validate_merge, forge_merge_back). While it runs, you can pause and resume its dispatch from the release panel (Pause / Resume).

Merge-back also acts as a gate: a workflow on main cannot be released while workflows branched off it have not been merged back. In that case the release panel lists the blocking workflows, each with its own Merge back button.

Creating a release

Create release is meant to be offered for completed workflows whose source branch is main or develop, once all their tasks are done and every child workflow has been merged back. You pick the workflows to include and a version.

Beta note: this gate is not fully wired yet. A completed merge-back currently marks the child workflow Released rather than the Merged status the readiness check looks for, so a parent workflow with child workflows may not unlock Create release even after all of them have merged back.

The version must be semver (v1.2.3 or 1.2.3). The cockpit suggests the next version by bumping the latest released one based on the scopes of the included workflows:

Included workflow scope	Suggested bump
Greenfield or Brownfield — Major	major
Brownfield — Minor	minor
Anything else	patch

If the project has no previous release, the suggestion is computed by bumping v0.0.0 — for example v0.0.1 for a patch-scope release or v1.0.0 for a major one. If the stored previous version is not valid semver, the suggestion falls back to v1.0.0.

Creating the release sets up everything needed for agents to execute it:

• a release branch named release/{version}/base, created from the target branch by a connected CLI,
• a hidden execution workflow using the built-in forgeai-release-management skill,
• one critical-priority Merge: <branch> task per included workflow,
• a Finalize: tag <version> task that is blocked until every merge task completes.

Two guards apply: only one active release can exist per project at a time (creating a second one fails with "A release is already in progress for this project"), and a version number cannot be reused unless the earlier release was cancelled or failed.

How the merges execute

Release and merge-back tasks are dispatched to your connected CLIs like regular board tasks, but they jump the queue — the dispatcher orders them ahead of all standard board tasks. Agents merge each workflow branch into the release branch and finally tag the version, using the release MCP tools (forge_release_merge, forge_release_tag, forge_release_notes).

The Releases page tracks a per-branch merge state: pending, merging, conflict, merged, or failed. Beta note: the CLI does not yet report merge progress back to the cockpit, so branches currently stay at pending while the agents work — follow the release status and your terminal for progress.

Merge agents resolve most conflicts on their own; they only escalate when a conflict requires an architectural decision. When that happens, the task enters Awaiting Input and the release panel shows an Agent needs your input prompt. Release tasks belong to a hidden execution workflow, so they never appear on the Kanban board, and the panel's reply box is not wired up yet in the beta — reply from the terminal:

forge session respond <taskId> "Keep the version from the release branch"

Release statuses

Status	Meaning
Preparing	The release branch and merge tasks are being executed by agents.
Review	Every branch is merged into the release branch; the release awaits approval.
Releasing	The release is approved; the finalize task creates and pushes the version tag.
Released	The tag is pushed. The release is complete.
Failed	Release execution failed. The version number becomes reusable.
Cancelled	You cancelled the release before it finished. The version number becomes reusable.

Beta note: the current agent flow does not pause at Review. The finalize task is unblocked by task dependencies alone, so the tag is pushed as soon as all merge tasks complete, and when the last release task finishes the release moves straight from Preparing to Released without stopping in Review or Releasing. An approval step (Approve & Release with optional release notes, plus Cancel) exists in the code and is guarded server-side to the Review status, but no screen currently opens it — releases cannot be approved or cancelled from the cockpit yet.

When a release completes:

• all included workflows get the status Released,
• the release shows up in the project's release history.

Beta note: the included workflows' tasks are not archived yet — they remain visible on the Kanban board after the release completes.

Where to see releases in the cockpit

Releases live inside each project at /orgs/[orgSlug]/projects/[projectSlug]/releases — in the UI, Projects → your project → Releases.

The page shows a branch graph of your standard workflows and their release state. The toolbar displays the Latest (most recent) and Highest (by semver) released versions, a search box, a release-history dropdown listing each completed release with its version, date, and workflow count, and a pause toggle. Dispatch of release tasks can be paused per release, on top of the org, project, and board-level pause switches described in Tasks & the live board.

Opening a release locally

Each entry in the release history has a copy button for the matching CLI command:

forge release open <releaseId>

This fetches the release from the cockpit, clones or updates its release branch under ~/.forgeai/open/<projectSlug>/<branchSlug>/, and opens the directory with your configured opener (terminal, vscode, or finder — see the CLI command reference). It requires an authenticated CLI (Authenticating the CLI) and a project with a repository URL.

If release tasks stay in pending, check that a CLI is connected and has free agent slots — see Troubleshooting & FAQ.