The journey of a scan

Six stages, always in the same order. Each one either succeeds or stops the scan — no stage guesses on behalf of the one before it.

1. Requested A scan is asked for — on a schedule, by someone pressing a button, or by an event such as new work arriving on a repository. The request names the repository; the exact commit is resolved later, when the code is actually fetched, so the result always reports what was really read.
2. Queued Requests wait in a queue rather than starting immediately. Analysis is heavy work, and running an unbounded number at once would make every scan slower and less predictable. The queue is ordered by priority, and customer work always outranks our own background work. We continuously re-measure a large public corpus of open-source projects to keep the system honest; that work runs at the lowest possible priority and is overtaken by any customer scan. The most a customer waits behind background work is the one scan already running.
3. Prepared The code is fetched and placed in a private working area. This is the point where the exact commit is established and recorded — from here on, everything refers to that one state. The working copy exists only in memory, never on a disk, and is removed when the scan finishes. Where the code runs covers this in detail.
4. Analysed The analysis engine runs against the prepared code inside a locked-down, disposable container. This is the longest stage and the one that does the real work: reading the code, building it, running its tests, and running the individual checks that produce findings. Different checks need different things. Some only read source text. Some need the project to compile. Some need its test suite to actually execute. When one of those prerequisites cannot be met, that specific check reports that it could not be established — it does not fail the whole scan, and it does not quietly score zero. Scans vary in length accordingly, from minutes for a small project to substantially longer for a large one that must be built and tested.
5. Scored The engine's raw measurements are folded into scores under the rubric version in force for that run. Scoring is a separate step from measuring, on purpose: the measurements are facts about the code, and the scoring is the stated policy applied to those facts. Keeping them apart is what allows a result to be re-checked, and what makes the reproducibility promise possible.
6. Delivered The scores, the findings behind them and the rendered report are stored and made available. The working copy of the code is discarded. What remains is the result and its evidence — not the source it was derived from.

A scan can fail — a repository may be unreachable, or the analysis may not complete. A failed scan is recorded as a failure. It does not produce a low score, and it does not silently produce a partial one presented as complete.

A scan can also complete in a degraded state: it ran, but some part of the analysis could not be performed. That is recorded too, and the affected measurements report themselves as not established. A result that could not measure everything says so.

The principle underneath all six stages. Every stage is allowed to stop, and every stage is allowed to say "I could not do this". None of them is allowed to invent a value to keep things moving. Most of the design exists to make sure a missing measurement stays visibly missing instead of turning into a number.

• From GitHub App to your first baseline — follows the same stages from the outside, as a first-time user meets them.