Terraform and OpenTofu Registry Deprecation and Staleness Gate

Give this Actor the provider and module sources of a project, with the version constraint each one carries today. It reads the public Terraform Registry or the public OpenTofu Registry and returns one row for each source: the latest version, the latest version the constraint still allows, how many major versions the upgrade crosses, how long it has been since the last release, the deprecation or archive state, the source repository, and an upgrade class.

Who this is for

A platform engineer who plans a provider or module upgrade, and who must know which sources are unsafe to move to before the work starts. Run it once each month in the upgrade planning cycle, and once before each quarterly platform maintenance window.

What the Actor does

1. Reads 1 to 300 registry sources, each with a kind and a version constraint.
2. Resolves each supported source against the chosen public registry.
3. Parses the constraint locally and picks the highest release the constraint still allows.
4. Measures the upgrade distance: major versions crossed, minor versions behind, and releases behind.
5. Measures the release age: the date of the newest release and the days since that date.
6. Reads the registry deprecation, archive and warning fields.
7. Writes one dataset row for each source, and one run-summary record with the gate verdict.

The Actor makes HTTP GET calls to the public registry only. It runs no Terraform or OpenTofu binary, reads no state file, uses no cloud credential, no browser, no proxy, no language model and no paid API.

Registries and endpoints

Registry	Kind	Endpoints
terraform	provider	registry.terraform.io/v1/providers/{ns}/{name} and /v2/providers/{ns}/{name}
terraform	module	registry.terraform.io/v1/modules/{ns}/{name}/{provider}
opentofu	provider	api.opentofu.org/registry/docs/providers/{ns}/{name}/index.json
opentofu	module	api.opentofu.org/registry/docs/modules/{ns}/{name}/{target}/index.json

Input

Field	Type	Default	Meaning
sources	array	six-source sample set	1 to 300 sources. Each item takes source, an optional kind (provider, module or auto) and an optional constraint. A plain string is also accepted.
registry	string	terraform	terraform or opentofu.
staleDays	integer	365	A source with no release in this many days gets the stale flag.
failOnDeprecated	boolean	true	A deprecated, archived or blocked source counts as a gate failure.
failOnStale	boolean	false	A stale source counts as a gate failure.
failOnMajorBehind	integer	0	A source that is this many majors behind, or more, counts as a gate failure. 0 turns the rule off.

Example:

{
  "sources": [
    { "source": "hashicorp/aws", "kind": "provider", "constraint": "~> 5.0" },
    { "source": "terraform-aws-modules/vpc/aws", "kind": "module", "constraint": "~> 5.0" }
  ],
  "registry": "terraform",
  "staleDays": 365
}

Source addresses

• A provider address is namespace/type, for example hashicorp/aws.
• A module address is namespace/name/provider, for example terraform-aws-modules/vpc/aws.
• A leading registry host is accepted and removed: registry.terraform.io/hashicorp/aws.
• A submodule path is removed and reported: terraform-aws-modules/iam/aws//modules/iam-role.
• A Git, HTTP, archive, local-path or private-registry source cannot be read from the public registry. It gets a SKIPPED row with the reason, and it is never charged.

Constraint syntax

The Actor reads the constraint syntax that Terraform and OpenTofu share: = 1.2.3, != 1.2.3, > 1.0, >= 1.0, < 2.0, <= 2.0, ~> 4.16, and a comma separated AND list such as >= 2.0, < 4.0. A bare 1.2.3 means = 1.2.3. An empty constraint allows every release. A prerelease is never picked unless a constraint names that prerelease. A constraint the Actor cannot read does not stop the run: the row keeps constraintValid: false and reports the registry facts without an upgrade distance.

Output

One dataset row for each input source, plus one runSummary record.

Field	Meaning
recordType	source or runSummary.
inputSource, label, kind, registry	The address as given, the label, the resolved kind, and the registry that answered.
namespace, name, target, submodulePath	The parsed address.
constraint, constraintValid, constraintSatisfied	The constraint, whether it could be read, and whether any release meets it.
status	RESOLVED, NOT_FOUND, SKIPPED or ERROR.
latestVersion, lastReleaseDate, daysSinceLastRelease	The newest release and its age.
latestSatisfyingVersion	The highest release the constraint still allows.
majorVersionsBehind	How many major versions the upgrade to the newest release crosses.
minorVersionsBehind, releasesBehind	Smaller upgrade distance measures.
stale	True when daysSinceLastRelease is at or above staleDays.
deprecated, deprecationReason, deprecationSignal, registryWarnings	The deprecation state and the registry field that states it.
sourceRepositoryUrl	The source repository the registry names.
totalVersions, tier, verified, downloads	Registry metadata.
upgradeClass	current, minor-behind, major-behind, stale, deprecated, skipped or unknown.
flagged	True for a deprecated or stale source. This is the charged flag.
gateFailure	True when the row breaks one of the three gate rules.
error	The registry error for an ERROR row.

upgradeClass takes the first class that fits, in this order: deprecated, stale, major-behind, minor-behind, current. A row the Actor could not resolve gets unknown, and a source that is not a public registry address gets skipped.

The run-summary record repeats the thresholds and carries the counts: sourceCount, checkedCount, skippedCount, notFoundCount, errorCount, deprecatedCount, staleCount, majorBehindCount, minorBehindCount, currentCount, flaggedCount, gateFailureCount, registryCalls, deprecationFieldPresentCount and gateVerdict.

deprecationFieldPresentCount states for how many checked sources the registry carried a usable deprecation, archive or warning field. Read it to see how much of the deprecation half of the report the registry itself supports.

The gate verdict is not a run failure

A failed gate, an unreachable source and a source with no findings are all business results. The run reports them in the dataset and in the status message, and ends as SUCCEEDED. A run fails only on a real malfunction.

Pricing: pay per event

Event	Unit	Counted as
registry-source-checked	One provider or module source resolved against the registry	One charge for each unique address that the Actor sent to the registry. Two rows that name the same address share one lookup and one charge. A NOT_FOUND or ERROR address is charged, because the registry call was made. A SKIPPED row is never charged, because it never reaches the registry.
deprecated-or-stale-source-flagged	One source with a deprecation notice or a release gap above the threshold	One charge for each unique checked address whose row is deprecated or stale.

Limits

• 1 to 300 sources for each run, at most 6 registry calls at a time.
• 25 second timeout and an 8 MB response cap for each registry call.
• The Actor reports what the public registry states. A provider that is deprecated in its repository, but that carries no registry field, is reported through the description and warning text signals only.
• Release age comes from the newest release the registry lists. The Terraform Registry gives one publish date, for the newest version; the OpenTofu API gives a date for every version.
• For an OpenTofu module the API states no repository field, so sourceRepositoryUrl follows the registry's own GitHub naming rule (github.com/<namespace>/terraform-<target>-<name>). Every other case takes the repository the registry states.
• The run-summary counts are counts of rows. The two charge counts, chargedSourcesChecked and chargedFlagsRecorded, are counts of unique addresses.

Development

uv sync
uv run pytest
uv run ruff check .