The module registry shares private OpenTofu modules across your
organization’s workspaces. Modules are published from GitHub tags and used
with a standard module block. Only members of your organization can see or
download them.
Use a module
Reference a registry module with its address and a version constraint:
module "network" {
source = "stackship.run/acme/network/aws"
version = "~> 1.2"
}The address has four parts:
| Part | Example | Meaning |
|---|---|---|
| Host | stackship.run |
Always stackship.run |
| Organization | acme |
Your organization slug |
| Name | network |
The module name |
| System | aws |
The provider the module targets |
Copy a module’s exact address from its page under Registry.
tofu init picks the newest published version that matches your version
constraint. Use an exact version, such as version = "1.2.0", to always get
the same package. Prerelease versions are used only when you name them
exactly.
If you rename your organization slug, every module address changes and you
must update source in your configurations.
Authenticate
OpenTofu uses the same credentials it uses for StackShip workspaces.
| Where | How |
|---|---|
| Your machine | Run tofu login stackship.run |
| CI | Set TF_TOKEN_stackship_run to a service-account token |
| StackShip runs | Nothing to do — runs authenticate automatically |
An apply reuses the modules its plan downloaded, so a module change between plan and apply can’t affect an approved apply.
Browse modules
Registry in the sidebar lists your organization’s modules. A module’s page
shows its README.md and its versions, each with the GitHub repository, tag,
commit, and publish time.
Versions marked Deprecated still work for existing configurations; the page shows the deprecation reason.
Who can do what
| Role | Can |
|---|---|
| Member | Browse, use, and download modules |
| Owner, admin | Also create, publish, deprecate, restore, and delete modules |
Troubleshooting
Error from tofu init |
What to check |
|---|---|
401 |
Run tofu login stackship.run, or set TF_TOKEN_stackship_run |
| Module not found | Check the organization slug, name, and system in source, and that you’re signed in to the right organization |
| No matching version | Check that a version matching your constraint is published on the module’s page |