Skip to main content

Register a Module

Last updated on
Module Registry 2.0 Beta

The onboarding pipeline flow, Artifact storage, auto-sync, and org/project-scoped modules are in beta. Contact Harness Support to enable these features. Go to Module Artifacts for a detailed explanation of how artifact storage and the onboarding pipeline work.

Registering a module connects a Git repository to the Module Registry and makes its tagged versions available for consumption. During registration, you configure the module's repository, storage type, scope, and onboarding pipeline.

You can register a module through the Add New Module wizard or the harness_platform_infra_module Terraform resource.

Before you begin​

  • Git tag: A module version is a Git tag. Create a tag or release on your module's repository before you register, otherwise there are no versions for the registry to pick up. Go to Tags to tag with Harness Code Repository.
  • Module structure: Your repository must follow the expected layout. Go to Set Up a Module to prepare the repository.
  • Pipeline permissions: You need View, Create/Edit, and Execute permissions on Pipelines in the target project. Go to RBAC in Harness to configure roles.
  • Git authentication: Your Git connector must be able to access the module repository. This is separate from the TF_TOKEN_app_harness_io authentication used when a workspace consumes the registered module at runtime. Go to Use a Module to configure runtime authentication.
Delegate version

If you connect to your code repository through a delegate, ensure the delegate version is 25.01.85000 or later.

Understand module tags and versions​

The Module Registry uses three different tag-related concepts. Only Git tags represent module versions.

TermWhat it is
Tags field on the moduleOptional organizational labels inside Harness for search and filtering. These are not versions.
Git Tag Pattern fieldA wildcard filter (for example, SQSv*) that limits which Git tags become module versions.
Git tags in the repositoryThe actual Git tags that correspond to module versions.

For example, if your repository has tags SQSv.1.0.0, SQSv.1.0.1, S3v.1.0.0, and S3v.1.0.1, set Git Tag Pattern to SQSv* to onboard only the SQS module versions.

Module scopes​

You can register a module at the account, organization, or project scope. The scope controls where the module is visible and who can consume it.

ScopeVisibility
AccountAvailable to all organizations and projects in the account.
OrganizationAvailable to all projects within the selected organization.
ProjectAvailable only within the selected project.

Regardless of module scope, the onboarding pipeline always runs inside a Harness project. Select the org and project in Step 2 of the wizard where your shared onboarding pipelines live.

Register a module​

Registration is a three-step wizard titled Add New Module. You can also register using the Terraform/OpenTofu provider.

Register a module from a subdirectory​

By default, the registry expects the root module (main.tf) at the repository root and submodules inside a modules/ folder. If your module does not sit at the repository root, for example in a monorepo holding multiple modules, set the Folder Path field when you register it. Folder Path maps to the repository_path argument on the harness_platform_infra_module Terraform resource.

Setting Folder Path re-roots all resolution, including where the registry looks for the modules/ folder, so submodules are discovered relative to the path you set.

Example: Root module lives in terraform/infrastructure:

.
├── README.md
└── terraform/
    └── infrastructure/
        ├── main.tf
        ├── variables.tf
        ├── outputs.tf
        └── modules/
            └── submoduleA/
                └── main.tf

Set Folder Path during registration:

  1. In the New Module wizard, configure the module name, provider, connector, and repository.
  2. In the Folder Path field, enter the path from the repository root to the directory containing the root module, for example terraform/infrastructure.
  3. Complete the remaining fields and click Create.

Or set the equivalent repository_path argument in Terraform:

resource "harness_platform_infra_module" "example" {
  name                 = "my-module"
  system               = "aws"
  repository           = "tf-aws-vpc"
  repository_branch    = "main"
  repository_path      = "terraform/infrastructure"
  repository_connector = "account.mygithub"
}
Submodules not appearing?

Confirm that Folder Path points at the directory containing main.tf and that submodules sit in a modules/ folder directly under that path. Metadata collection is one level deep, so deeply nested submodules are not surfaced even though they remain usable through the // subpath syntax.

Troubleshooting​

Onboarding pipeline fails on the clone step in Harness IaCM Module Registry

Verify that the Git connector has read access to the module repository and that the repository name and branch are correct in the module configuration.

No module versions appear after the onboarding pipeline completes in Harness IaCM

Confirm that the repository has at least one matching Git tag. The onboarding pipeline processes tagged versions; branches are not synced.

Auto-sync does not trigger on new tags in Harness IaCM Module Registry

Confirm that Enable auto-sync is selected and that the webhook was created successfully. Select the pipeline's Triggers tab to verify the trigger is active. If it shows a Failed status, verify that the Git connector has permissions to register webhooks on the repository, then delete the failed trigger and re-enable auto-sync.

Next steps​

  • Go to Explore Module Details to review your registered module's parsed metadata and published versions.
  • Go to Use a Module to reference the registered module from an OpenTofu or Terraform configuration.
  • Go to Test a Module to set up automated module testing.