Releases

Production publication is Git-triggered and is never assembled from an out-of-band contract edit. A provably non-economic default-branch change may publish runtime contract state directly. A full versioned release—including economic contract work plus customized frontend and repository-docs artifacts—comes from an immutable tag in the managed repository.

farthershore business publish is the first-activation command for a draft business. It previews the initial semantic version, creates the first GitHub Release, and makes the business live. After that activation, a repo-backed business is code-managed: repeating business publish returns MANAGED_BY_CODE. Subsequent versioned releases are published in the managed repository through GitHub, whose release webhook resolves the tag to its immutable commit and queues the production build.

A non-economic default-branch push may apply runtime-safe contract work without waiting for billing reconciliation. An economic change—a plan's kind or recurring price, a pricing catalog, funding buckets, spend policy, meter-route admission bounds, or another subscriber-money boundary—must remain behind the reviewed GitHub Release. Use the Apply Timeline's semantic diff and farthershore commercial-release diff instead of guessing from which files changed. Every economic publish produces an immutable, content-addressed commercial release whose activation reaches new subscriptions; existing subscriptions keep their pins.

Prepare the exact commit#

git switch main
git pull --ff-only origin main
farthershore build --format json
approved_sha="$(git rev-parse HEAD)"
git push origin main
farthershore apply-timeline inspect acme "$approved_sha" --env production --format json

Require the repository checks for the current SHA. A prior green commit is not release evidence.

Activate the first draft#

Use this section only while business status is DRAFT. Preview the initial release:

farthershore business publish acme --dry-run --format json

The preview returns the computed bump, first version, reasons, and any refusal. Review that output with the repository diff. A first real release starts at v0.1.0.

The platform refuses an unchanged release and refuses a breaking release unless the caller explicitly accepts it. --accept-breaking is consent, not a way to silence an unknown diff.

You can request the first bump or version when release policy requires it:

farthershore business publish acme --bump minor --dry-run --format json
farthershore business publish acme --version v2.0.0 --dry-run --format json

Run the final non-dry command only after the exact commit, version, and semantic diff are approved:

farthershore business publish acme --format json --idempotency-key <persisted-business-publish-attempt-key>

The command creates the first published GitHub Release in the managed repository and activates the draft business.

Publish a later version#

For an already-active repo-backed business, first push the reviewed commit and require its repository checks. Inspect the default-push Apply Timeline entry: a non-economic runtime change may already publish from that commit, while an economic or indeterminate change remains deferred.

Create the next immutable semantic-version tag and published GitHub Release in the managed repository. For an agent with an authenticated GitHub CLI, the confirm-gated effect is:

git switch main
git pull --ff-only origin main
farthershore build --format json
approved_sha="$(git rev-parse HEAD)"
git push origin main
farthershore apply-timeline inspect acme "$approved_sha" --env production --format json
git tag -a v1.2.3 "$approved_sha" -m "v1.2.3"
git push origin v1.2.3
gh release create v1.2.3 --verify-tag --target "$approved_sha" --title "v1.2.3" --generate-notes

Choose the version from the reviewed semantic and subscriber impact; do not copy v1.2.3 blindly. Draft and prerelease GitHub releases do not trigger production. The release webhook must carry the approved 40-character SHA and the tag must still resolve to that SHA; do not target a branch such as main.

Verify serving state#

Release creation is only the handoff. Confirm the release apply:

farthershore apply-timeline inspect acme <release-tag> --env production --format json
farthershore business status acme --format json
farthershore frontend status acme --ref "$(git rev-parse HEAD)" --wait --format json

Require all of the following:

• the timeline entry has the expected releaseTag and commitSha;
• its publish phase settled successfully;
• business status reports the expected latest release and live: true;
• if frontend source changed, the expected frontend release settled too.

The business apply and frontend build are separate pipelines. There is no CLI frontend-deploy verb: the GitHub Release triggers production; frontend status observes the latest known build for the source revision in the current checkout. It does not identify a specific webhook delivery; exact attempt proof requires a build id where the trigger returned one.

Recover a contract change#

The durable fix is forward: revert or correct the Business program in Git, validate it in preview, merge, and publish a new release. That restores the desired contract while keeping Git and platform state aligned.

Rollback a publish workflow#

For urgent operational compensation, identify the prior publish workflow execution id and enqueue rollback:

farthershore apply-timeline inspect acme <bad-release-tag> --env production --format json
farthershore business rollback acme <workflowExecutionId> \
  --reason "restore the prior serving snapshot" \
  --idempotency-key rollback-<workflowExecutionId> \
  --format json

This command does not move the Git tag, revert a commit, or change business/. It starts an asynchronous rollback workflow using the snapshot captured by the source publish workflow. On the commercial side a rollback appends a new, higher release-log sequence that points at the older immutable release — usage already admitted under the rolled-back release is still rated under it, and no other business is affected. A cross-business or unknown workflow id is hidden as not found; an already rolled-back or cancelled workflow returns WORKFLOW_NOT_ROLLBACKABLE.

A 202/status: enqueued response proves only that compensation was queued. Record the returned rollbackWorkflowExecutionId. Where workflow-inspector access is available, inspect that new execution directly:

farthershore workflows show <rollbackWorkflowExecutionId> --format json

Then read back business status and every affected serving, plan, customer, and billing surface. The Apply Timeline still identifies the source publish; do not misrepresent its old status as the rollback workflow's status. If no rollback snapshot was captured, or compensation cannot converge every external surface, complete the forward Git fix and retain the rollback evidence for support.

Roll back only the frontend#

If the Business contract is correct and only the hosted frontend artifact is bad, reactivate a prior frontend release:

farthershore frontend status acme --format json
farthershore frontend rollback acme --release-id <releaseId> --format json

This does not change routes, plans, meters, billing, or the repository contract. For production, it pins the frontend target. Later production builds still run but do not autoactivate; after the forward fix produces a successful release, activate that reviewed release id explicitly with frontend rollback and verify the active id and pin state. There is no separate unpin command.

Preview rollback requires --env <environment-id> and does not pin. The next successful build for that preview environment autoactivates, so use preview rollback only as temporary containment and verify the active release after each subsequent build.

See Apply and recover and Prepare a production release.