Pin the deployed commit so reports map to source

A bug report is a statement about the past. The visitor saw a result produced by the code that was running at that moment. By the time anyone investigates, the main branch may have moved several times.

If you do not record which commit was live, every investigation carries an unstated assumption: that the code you are reading is the code that failed. That assumption is frequently wrong, and when it is wrong it is expensive.

What goes wrong without a recorded commit?

Three distinct failures, all of which look like confusion rather than a process gap.

You investigate code that never ran. The file changed after the report arrived. You read the current version, find nothing wrong, and conclude the report is invalid — while the defect sits in the version the visitor actually loaded.

You "fix" something already fixed. The behaviour was corrected in a later deployment. Without a commit reference nobody can tell whether the report predates the fix, so the report is re-investigated from scratch.

You cannot verify a claim. An investigation says the cause is a specific line. Against which version? A source claim without a revision is not checkable, and an unverifiable claim is an opinion.

All three waste the most expensive part of the process — the careful reading — on the wrong input.

What exactly should you record?

The full commit identifier of the build that served the visitor, captured at the moment the report is created.

Full, not abbreviated. A short prefix is convenient for humans and ambiguous for machines: prefixes can collide, and the collision rate grows with repository size. Recording the complete identifier removes the ambiguity permanently.

Recorded at report time, not at investigation time. If you look up "the current deployment" when someone finally opens the report, you have recorded when the investigation started, which is not the fact you needed.

Two related facts are worth keeping alongside it: which branch the deployment came from, and when it was deployed. Together they let you answer "was this report before or after that change" without archaeology.

How does a report get the commit into it?

The build needs to know its own identity, and the reporting path needs to carry it.

The usual approach is to inject the commit identifier into the build at build time — a value baked into the artefact rather than looked up at runtime — and to include it with anything the application reports. This is the same value that makes error monitoring useful, so you may already have it.

The subtle case is the visitor holding an old page. Someone with a tab open since yesterday is running yesterday's assets even though your server now serves today's. If the identifier is baked into the loaded build, the report correctly names the old commit. If it is fetched fresh at report time, it names the current one and quietly misattributes the report.

Should the revision be pinned or follow the branch?

Both are legitimate, and the difference is about who controls the mapping.

Following the branch head means the recorded revision updates to the latest commit on the registered branch whenever the connection is checked. This suits a website deployed continuously from that branch, provided the check happens after each deployment — otherwise the recorded revision drifts behind what is actually live.

Pinning an exact revision means you state the deployed commit explicitly, and it does not change until you change it. This suits a website deployed from tags or on a slower cadence, or any situation where you want the mapping to be deliberate rather than inferred.

The failure mode to avoid in both cases is silent drift: a recorded revision that no longer corresponds to what visitors are running. Whichever mode you use, the update step belongs in your deployment routine rather than in someone's memory.

What does this enable?

Once every report carries a commit, several things become straightforward.

You can read the exact source that produced the behaviour, so a source claim becomes verifiable rather than plausible. You can distinguish "still broken" from "already fixed" mechanically. You can group reports by build and notice that a cluster all arrived from one deployment, which is often the fastest possible diagnosis. And when a fix ships, you can say which commit contains it.

It also makes an honest unknown more useful. "We read this file at this commit and the code does not explain the reported behaviour" is a real finding that narrows the next attempt. "We looked and did not find anything" is not.

How IssueProbe uses the deployed revision

When you connect a website, IssueProbe accepts an SSH repository location, a default branch, and an optional deployed revision as a full 40-character SHA-1 or full 64-character SHA-256 value. An abbreviated revision is rejected.

Supplying a revision selects pinned mode, and that revision stays unchanged across later checks. Omitting it selects branch-head mode, where each successful repository check replaces the stored revision with the current remote branch head — which is why the check belongs in your deployment routine. A failed check keeps the last known revision rather than clearing it.

When a report becomes eligible for investigation, it copies the current registered revision as it enters the queue. A later repository check cannot change that report's revision, and a retry keeps the same one, so the investigation always reads the source that was recorded for that report. A later reinvestigation copies the newer current revision, which is what you want when you deliberately ask for a fresh look.

The investigation is isolated and read-only, and its result cites specific source locations at that revision — or states that the cause is unknown when the evidence does not support a conclusion. A human reviews the result before anything is sent to a visitor.

Read what makes a bug reproducible for the surrounding discipline, and giving a coding agent enough context for why an exact revision matters when something else reads your code.