---
title: "Module registry"
description: "Publish and consume private OpenTofu modules through the standard module registry protocol on stackship.run."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackship.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

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

| Part | Meaning |
| --- | --- |
| `stackship.run` | The registry hostname — the same host used by `cloud {}` and `tofu login` |
| `<org-slug>` | The organization slug, resolved when the request is served |
| `<name>` | The module name chosen at creation |
| `<system>` | The provider target, for example `aws` |

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:

```hcl
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:

| Credential | Where | How |
| --- | --- | --- |
| Interactive OAuth token | Local CLI | `tofu login stackship.run` |
| Service-account token | CI and automation | `TF_TOKEN_stackship_run` |
| Managed run credential | Managed plans | Injected automatically |

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](/registry/publishing).

## Provenance and integrity

Module versions are immutable. Each version permanently records:

| Field | Meaning |
| --- | --- |
| Repository | The GitHub repository the version was published from |
| Tag | The exact pushed tag, for example `v1.2.0` |
| Commit SHA | The full 40-character commit the tag pointed at |
| Archive SHA-256 | The digest of the stored package |

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](/registry/publishing)
- [State and native cloud](/workspaces/state) — discovery and `tofu login`
- [Managed execution](/runs/runners) — the dependency bundle replayed at apply
- [v1 REST API](/automation/api) — registry management operations

Source: https://docs.stackship.run/registry/index.mdx