Error "signature does not match" when creating a TAG release on Github repository integrated with a Private registry module

Problem

When you publish a new version of a private module to a GitHub repository integrated with the Terraform Enterprise private module registry, the operation fails. The webhook delivery details in GitHub show a 401 Unauthorized error with the message signature does not match.

Cause

This error typically indicates a stale or misconfigured webhook between Terraform Enterprise and the GitHub repository. The signature key used by Terraform Enterprise to sign webhook payloads no longer matches the secret configured in the GitHub webhook, causing GitHub to reject the request as unauthorized.

Solution

The most effective way to resolve this issue is to reset the connection by deleting the module from the Terraform Enterprise registry and then re-publishing it. This process automatically deletes the old webhook and creates a new one with a valid signature key.

This procedure does not affect the module's source code in your GitHub repository.

Step 1: Delete the Module from the Private Registry

1. In Terraform Enterprise, navigate to your organization's settings and select Registry.
2. Select the module that is experiencing the issue.
3. Click Manage module for organization.
4. Click Delete module.
5. Select the option Delete all versions for this provider for this module.
6. Type delete into the confirmation box and click Delete.

The module is now removed from your organization's private registry.

Step 2: Verify Webhook Deletion in GitHub

1. Navigate to your GitHub repository's webhook settings page. The URL follows this pattern: https://github.com/<your_profile>/<repo_name>/settings/hooks
2. Confirm that the webhook pointing to your Terraform Enterprise instance has been removed. If it still exists, manually delete it by clicking Delete and confirming the action.

Step 3: Re-publish the Module

1. In your Terraform Enterprise organization, navigate to Registry.
2. Click Publish and select Module.
3. Select the VCS provider connection for your GitHub repository.
4. Choose the repository containing your module from the list.
5. On the Confirm Selection screen, ensure the publishing type is set to Tag, which is the default.
6. Click Publish module.

After a few moments, the module will be published to your private registry. This action creates a new webhook in the GitHub repository. You can verify its creation by navigating to the repository's Settings > Webhooks page and confirming the presence of a new, active webhook pointing to your Terraform Enterprise instance.

Step 4: Test with a New Tag Release

1. In your GitHub repository, navigate to the Releases page.
2. Click Draft a new release.
3. In the Choose a tag dropdown, type a new version tag for your release (e.g., v1.0.1) and select Create new tag.
4. Provide a title for the release and click Publish release.
5. After the release is published, refresh the module page in the Terraform Enterprise registry. The new version tag now appears in the list, confirming the integration is working correctly.

Additional Information

• For more details on webhook troubleshooting, refer to the guide on How to verify a VCS webhook is being received by Terraform Enterprise.