Module registry

StackShip includes a private OpenTofu module registry. Organizations publish versioned modules from approved GitHub repositories by pushing semver tags, and consume them in any workspace or local run through OpenTofu’s standard module registry protocol. Every registry request is authenticated; there is no public or anonymous surface, and a request from another organization receives a uniform 404 rather than confirmation that a module exists.

Module addresses

A module’s source address is:

stackship.run/<org-slug>/<name>/<system>

Service discovery at https://stackship.run/.well-known/terraform.json advertises the modules.v1 protocol, so plain tofu init resolves these addresses without any CLI configuration beyond credentials.

The namespace is the organization slug at read time. Renaming the organization slug changes every module address; existing configurations must be updated to the new slug.

Consuming modules

Reference a registry module with a source address and a version constraint:

module "network" {
  source  = "stackship.run/acme/network/aws"
  version = "~> 1.2"
}

During tofu init, OpenTofu lists the module’s published versions, selects the newest version matching the constraint, and downloads a checksum-verified package.

Credentials

OpenTofu selects credentials by the source-address hostname, so every existing stackship.run credential path works unchanged:

Managed runs authenticate to the registry automatically during the plan phase: the runner already injects its attempt-bound rat_ credential as TF_TOKEN_stackship_run, and that credential carries registry:read for plan and speculative-plan phases. No runner or workspace configuration is required.

Applies never contact the registry. The plan phase records every resolved module in the run’s dependency bundle, and the apply replays those exact bytes offline. A registry outage therefore cannot affect an approved apply.

Version constraints

Versions are semver and ordered by semver precedence. Standard OpenTofu constraint syntax applies: an exact version = "1.2.0" pin always resolves the same package, and a range such as ~> 1.2 selects the newest matching published version at tofu init time. Prerelease versions can be published; OpenTofu selects a prerelease only when the constraint names it exactly.

The version listing includes deprecated versions and is capped at 1,000 versions per module.

Deprecation

An organization admin can deprecate a version with a reason. Deprecation is a flag, not a removal:

• existing version pins and matching constraints keep resolving;
• the version stays in the protocol version listing; and
• the dashboard and management API mark the version deprecated and show the reason.

A deprecated version can be restored. Individual versions cannot be deleted; deleting the whole module is the destruction mechanism. See Publishing modules.

Provenance and integrity

Module versions are immutable. Each version permanently records:

This provenance is visible in the dashboard and the management API, and audit events record who published each version and who downloaded it. Downloads stream from encrypted storage and are digest-verified before the response completes; a mismatch quarantines the version and fails the request instead of serving unverified bytes.

Access

registry:read is granted to every organization member and permits browsing, resolving, and downloading modules. registry:write is granted to owners and admins and permits creating, publishing, deprecating, and deleting modules. Unauthenticated protocol requests receive 401; authenticated requests outside the module’s organization receive 404.

Related pages

• Publishing modules
• State and native cloud — discovery and tofu login
• Managed execution — the dependency bundle replayed at apply
• v1 REST API — registry management operations