Skip to main content
By the end of this guide you will know which release introduced an error, which commits in that release are likely to blame, and you will have marked the issue resolved so that it reopens if the error comes back. This works because every hosted release is recorded with its commit range, and every error event carries the build that produced it. Forge can therefore join an error to the release it first appeared in, and your local git history narrows that release down to suspect commits (how errors are grouped).

Before you begin

  • A Forge project deployed to a hosted environment, with at least two releases (deploy a static site or a Go API).
  • The project’s git checkout, with the commits those releases were cut from. Suspect commits are read from your local history.
  • The obs:triage permission to resolve issues (credentials).
The example below is a static site: release v8.1.0 already threw a RangeError, and release v8.2.0 added a price formatter that throws a TypeError for a plan with no price.
1

List what the newest release opened

obs issues lists the open issues. --since-release keeps only those first seen in one release:
terminal
Without the flag, the older RangeError is listed too, as unresolved. It predates v8.2.0, so this release did not cause it.
2

Read the issue

Run this from your checkout, so forge can read the suspect commits from git:
terminal
  • at is the culprit: the function and file the error was raised in, after source maps resolved the minified stack.
  • first release names the release and the commit range it shipped. This line answers the question.
  • by version counts events per build. A browser error reports its frontend build id, so read it against the first release line.
  • suspect commits are the commits in that range that touched the culprit’s files and frames. Here both touched src/App.tsx, but only 6d656dae touched pricing.ts.
Add --json to hand the whole document, including the latest trace id, to an agent.
3

Line it up with what changed

obs changes puts promotions, issues and alerts on one timeline, newest first:
terminal
The TypeError opened four minutes after v8.2.0 was promoted, and the NewIssue alert followed.
4

Fix it and resolve it in the next release

Commit the fix, then mark the issue resolved as of the next release:
terminal
--in next dates the resolve to now. Events from the release that is live now are the bug you are fixing, so they do not reopen the issue. An event from any release promoted after now reopens it as regressed. If the fix already shipped, --in v8.3.0 dates the resolve to just before that release reached the environment.
5

Ship the fix and check the issue

Build and promote the fixed release (promote a release):
terminal
After users load the new release, only the older error is still open, and the fixed one is listed as resolved:
terminal
The resolved issue counts 7 events, not 5. Two page loads of v8.2.0 arrived after the resolve and did not reopen it. Its timeline in obs issue shows who resolved it and when.

What this does not do

  • It does not roll anything back. To get back to a good state fast, deploy an earlier release (recover from a bad deploy), then fix forward.
  • Suspect commits are a narrowing aid, not blame: they are the commits in the release’s range that touched the files in the stack. A commit that broke a caller in another file is not listed.
  • Resolving an issue changes its state only. It does not open a fix. To have an agent investigate new errors, see alerts to GitHub issues: an agent files an investigated issue, and a person decides what happens next.

Troubleshooting

Run obs issue from the project’s checkout. The issue and its other fields are still printed.
Your checkout does not track the file named in the stack, for example because it is a different repository. Run it from the checkout the release was cut from.
Browser errors report the frontend’s build id. The first release line maps the issue to the release that shipped that build.
For a release of a static site with no backend, obs check can return this even though the release opened an issue. Use obs issues --since-release to see what the release introduced.

Next steps

Go from an error to a reviewed fix

Turn the issue into an agent-written pull request, with a person approving at each step.

Debug production with an AI agent

Give an agent the same obs documents, plus logs and traces.

How release verdicts work

How obs check judges a promotion before and after.

Send OpenTelemetry from any app

Get the same issues for an app Forge does not deploy.

Dashboards and alerts

Source maps, issue states and the NewIssue and IssueRegressed alerts.

Querying with forge obs

Every obs verb, its JSON output and exit codes.