Scan lifecycle: when a published module version becomes consumable

How a module version becomes published

A module version is stored on publish and served on scan. Publishing writes the archive and creates the version as pending. The scan runs out of band. Only when results come back does the version become published, and only published versions appear in the registry protocol or resolve to bytes. Those are two separate events, and most of the confusion comes from the gap between them.

Making the publish step wait, or poll

Make the publish step wait for the verdict, or make it poll, so it never has to assume. The failure mode to design out is a pipeline that reports a successful publish and a downstream job that can't find the version thirty seconds later. The publish response tells you which of the two things happened, so read it.

A pipeline that assumes:

# publish, then immediately consume
terramantle modules publish
terraform init   # 404: no matching version

# the publish returned 201 with
# { "status": "pending" }

One that waits for the verdict:

# hold the request open until the scan
# settles (up to 15s), verdict in the body
curl -u "terramantle-bot:$TOKEN" \
  -X PUT --data-binary @module.tar.gz \
  "$REG/v1/modules/acme/vpc/aws/1.4.0?wait=true"

# 201 published  -> consumable
# 202 pending    -> poll below

And one that polls the status:

curl -u "terramantle-bot:$TOKEN" \
  "$REG/v1/modules/acme/vpc/aws/1.4.0/status"

# { "status": "published",
#   "scan_started_at": ...,
#   "scan_completed_at": ... }

The CLI reads the same distinction and says so: a settled publish prints its verdict, and a publish whose scan is still running prints pending (scan still running). A version that came back failed is not retried by republishing the same number, because versions are immutable. Rescan it, or publish the next version.

How state and plans are gated

State is gated the other way round: reads are never withheld. A state read returns the newest version for the workspace immediately, whatever its scan status. Pull your state one second after an apply and you get it. The scan runs behind you, and its verdict is applied at the next lock instead of at the next read.

Reads are not gated because Terraform reads an empty state response as no state at all and plans to create your entire estate from scratch. A registry that withheld state during a scan would convert a pending finding into a proposed rebuild of production. No finding is worth that, so the read path has no scan predicate in it.

The verdict lands at the lock. When the latest state version of a workspace fails an enforcing policy, the workspace is flagged and the next lock attempt is refused with 423, before any apply runs. Plan artefacts raise the same flag by the same route. The gate sits at the start of the next change, which is the first point at which refusing is useful rather than destructive.

What this design does not give you

Module scanning is a true gate: unscanned code is never served, so a backlog costs you availability and never silently costs you a check. State scanning is a different kind of control. The apply that wrote the offending state has already run by the time the scanner looks at it, so all you get is a fast stop on the next change. If the state scan queue is backed up, that stop arrives later, and the workspace stays applyable in the meantime. Pre-apply enforcement belongs to plan-stage checks, which run against the plan before it is applied rather than the state it produced.

For what the scanners look for across modules, provider binaries and live state, see supply-chain scanning. A pending version is invisible rather than listed and refused because the registry protocol has no way to express "exists but not ready", so leaving it out of the versions list is the only accurate answer.