Versions on the status page
Versions are available on every plan. For one project, open Usage and settings → Versions; with several projects, open the project’s detail view first. Version management and the release entry point do not add free deliveries or remove plan limits. You still decide when to release. After the free allowance is used up, you can still create versions and release tasks, but a new release task cannot start. Subscribe, then reapplyai-ready to that Issue to dispatch it. A release has no PR and does not count as one of the first 3 merged deliveries; it still needs an available slot to start.
A version is a GitHub milestone whose title is the version number, like v1.2.3. The section shows:
- Current version: the version Orbi is working towards, or Not set (works on every task handed to Orbi). View on GitHub opens the milestone, or your repository’s milestones when none is set.
- Unreleased versions: your open version milestones, with their Open Issues count. Other versions offer Switch to this version. The current one is marked Current version and offers Create release task, or View release task once it exists. With no open milestones this reads No open versions.
- New version: type a version and click Create and switch.
- Guide: a short folded explanation of the buttons.
The delivery scope
An open Current version limits freshai-ready pickup to that milestone; Issues outside it wait. The status page can offer Move to version or Switch to version. If the current milestone is closed and there is no newer open milestone, pickup runs without a milestone filter while keeping the configured value. If a newer open milestone exists, automatic advancement or a version-confirmation Issue depends on the repository’s auto_next_milestone policy. Existing deliveries resume independently of the fresh-pickup scope.
While no version is set, every ai-ready Issue is eligible. You do not need versions at all to use Orbi; they only matter once you want to ship in batches.
Version numbers must be a leading
v followed by dot-separated numbers, such as v1.2.3; anything else is rejected before anything is changed on GitHub.
Cut a release
When the work for a version is in, make it the current version with Switch to this version if it is not already, then click Create release task on its row. Orbi opens the Release Issue. While any other Issue in that milestone is still open, it leaves the release queued atai-ready until they are closed; this queueing has no time limit. After the milestone is ready, Orbi runs the release, updates the version file when applicable, tags and publishes the GitHub Release, and closes the Issue. Updating the version file affects your site only through your own release or deployment process.
The milestone requirement
The release scope comes from the milestone whose title is exactly the version, sov1.2.3 needs a milestone called v1.2.3. Create and switch and Create release task both create that milestone for you if it does not exist; if you write a release Issue by hand, make sure the milestone exists.
If a release stops because the milestone is missing, the blocked Issue on the status page offers Create the version and continue.
If creating a release task or switching versions reports an error
The version file
Orbi detects how your project declares its version, checking in this order:pyproject.toml, package.json, pom.xml, build.gradle, build.gradle.kts, gradle.properties, Cargo.toml, composer.json, pubspec.yaml
If none is present, a release created from the status page is tag-only: no version-file update, just the tag and GitHub Release. A failure to read the repository tree is an error to retry; a successful read finding no supported file is a valid tag-only result. The page action remembers what it found for the repository, so if you add a version file later, write the Release Issue yourself with - version_file: (below).
Writing the Release Issue yourself
The buttons are a convenience. You can create the Release Issue by hand instead: label itai-ready and ai-release, and put it in the milestone whose title is the version, for example v1.2.3. Orbi then takes the version and scope from that milestone and the base branch from the repository settings, and looks for a version file in the order above. If it finds none, the release stops and asks you to add the optional ## Release section with - version_file: none (tag-only) or the file to use.
The optional section sets the fields explicitly:
version and base_branch are required, a duplicated or unknown field fails immediately, version must match the milestone title, and exactly one of scope_from_milestone or scope must be given. To list the scope explicitly, write - scope: followed by one - #N line per item. Inside the section, an omitted version_file means pyproject.toml.
What Orbi checks before it tags
The gates run in order, and a gate that cannot be checked counts as failed. The starting base is frozen first. The release starts from a specific base-branch commit. When a version bump is needed, that produces the version commit to be released; the checks and tag must refer to the actual release commit. Milestone admission comes before execution. Another open Issue in the milestone keeps the release unclaimed. If a delivery appears after admission, the in-run gate waits for same-milestoneai-in-progress, ai-pr-opened or ai-fix-needed work, with its own default 30-minute bound. A bare ai-ready label is not an in-run delivery wait. Open PRs alone are not a release gate.
CI must be green on the release commit. This is the test acceptance, and it is the part worth understanding properly:
Your repository’s checks determine the automated evidence available. With no observed CI, the release can proceed with explicit no-checks evidence; that does not prove tests passed. Once CI has been observed on the base, a newly pushed version commit with no checks yet must wait for them to register. Checks that are pending or failed cannot be treated as passed.
A pending check is not a failure: the gate waits for the final conclusion, up to 30 minutes by default, reporting progress while it waits. A timeout is reported as a timeout, never disguised as a CI failure.
Every scope item is verified live. Each item must be a merged pull request, or an Issue closed as completed. Checkbox state in the Issue body is ignored entirely — the check goes to the GitHub API. An Issue closed as “not planned” is recorded as excluded and left out of the changelog.
What it produces
- An annotated tag at the release commit, pushed normally — never with
--force. An existing tag is never moved; a conflicting tag stops the release. A resumed release can use its existing tag commit when that commit is already in the base branch’s history. - A GitHub Release whose notes carry the full evidence: version, tag, release commit, per-item scope evidence, gate evidence and test evidence.
- The milestone closed.
ai-blocked and is not retried automatically; after you fix the cause, replace ai-blocked with ai-ready and it resumes rather than starting over.
When a release fails
A red or timed-out CI takes the normal failure path and the Issue is markedai-blocked with the reason.
The version bump may already be on your base branch at that point, which is an acceptable state: the bump is idempotent, so repairing CI and re-running prepares the same version again safely.
Why releases stay manual
You decide the version and release policy. Start a release manually with the page action or anai-ready + ai-release Issue, or use the engine’s configured milestone workflow after confirming its version decision. The release state machine then performs the checks and publication; it does not independently decide product scope.
The release state machine is the engine’s, not Cloud’s. Its full reference — every gate, the resume behaviour and the evidence it writes — is at docs.orbi.build/workflow.