Publishing modules

Link a GitHub repository to a module, and each semver tag you push to it becomes a new module version.

Before you start

• You need the owner or admin role.
• The StackShip GitHub App must be installed on the repository.
• The module’s .tf files must be at the root of the repository. Each repository can back one module; subdirectories and monorepos of modules aren’t supported.

Create a module

1. Open Registry and select Publish module.
2. Enter a Module name — lowercase letters, numbers, and hyphens, up to 64 characters. The name can’t be changed later.
3. Enter the Provider system the module targets, such as aws (lowercase letters and numbers, up to 32 characters).
4. Choose the Repository.
5. Select Create module.

To publish tags that already exist, use Sync tags.

Publish a version

Push a semver tag:

git tag v1.2.0
git push origin v1.2.0

• v1.2.0 and 1.2.0 both publish version 1.2.0.
• Prerelease tags such as v2.0.0-rc.1 are allowed.
• Tags that aren’t semver are ignored.

Each version records the repository, tag, and commit it came from. Published versions never change: pushing a tag for a version that already exists with different contents is rejected.

Sync tags

Sync tags on the module’s page publishes up to 50 unpublished semver tags, newest first. Use it after you first link a repository or if a tag push didn’t show up. Run it again if more tags remain.

Check publishing history

The module’s page lists every publishing attempt, its status, and the failure code of any failed attempt. Common causes:

• the tag moved to a different commit before it was published — push a new tag;
• the archive is too large or contains symbolic links or unsafe paths.

Deprecate or restore a version

Deprecate a version to warn people away from it without breaking anyone.

1. On the module’s page, select Deprecate next to the version.
2. Optionally enter a reason (up to 512 characters).
3. Confirm.

Deprecated versions still resolve for existing version constraints and pins. Select Restore to undo. You can’t delete a single version.

Replace the repository

Select Replace repository on the module’s page and choose another repository. Existing versions stay published.

Delete a module

Under Danger zone, select Delete module and confirm. The module and every version are removed immediately, and any configuration that uses it fails on its next tofu init. Prefer deprecation when you can.

API

Send an Idempotency-Key header with each request that changes data.

Audit events

Registry activity appears in the audit log with actions that start with registry.module.: created, source_updated, version_published, version_deprecated, version_restored, version_downloaded (at most once per hour per token and version), sync_requested, integrity_violation (a tag tried to republish a version with different contents), and deleted.

Next steps

• Module registry
• GitHub source connections
• REST API