GitHub Webhook Secrets and the Terraform Public Registry
New semver tags in GitHub can fail to appear on registry.terraform.io when the Terraform Registry webhook’s Secret in GitHub no longer matches what the registry uses to verify deliveries. GitHub signs each delivery with that secret; the registry must validate the signature with the same value. This article states that model, what breaks when the two sides diverge, and how to recover using HashiCorp’s documented steps.
1. Overview
- Model: GitHub computes an HMAC signature for webhook payloads (see Validating webhook deliveries). The registry endpoint must verify it using the same secret tied to your module’s integration.
- Failure mode: Updating Secret only under GitHub → Settings → Webhooks changes what GitHub signs with. The registry does not read that field from your repo; it keeps the secret from the integration that created or last reconciled the hook. Signatures then fail and new versions do not publish.
-
Recovery: Keep a single webhook to
https://registry.terraform.io/hooks/github, run Resync Module from the registry UI, then confirm deliveries: push a new semver tag or use GitHub’s Redeliver on a failed delivery for the tag push you still want published (same payload, signed again with the current secret). If publishing still fails, use registry support.
This guide is for the public Terraform Registry and public GitHub modules. Terraform Enterprise and other private registries use different hosts and procedures.
2. Prerequisites
- Module already published on the Terraform Registry from a public GitHub repository
- Permission to use Manage Module on the module page and to edit Webhooks on the GitHub repository (Settings → Webhooks)
- A semver tag to test with (push a new one, or reuse an existing tag whose registry publish failed and still needs to succeed), per module publishing
3. What not to do
Do not paste a new random value into the webhook Secret in GitHub alone, expecting the public registry to pick it up. There is no documented self-serve screen on the registry where you paste the same value to pair it. Unilateral edits in GitHub desynchronize signing and verification.
If you already did that, treat the next sections as recovery, not prevention.
4. Recovery: one webhook, then Resync
Per the Terraform registry FAQ, Resync for a module makes the registry ensure the repository has a webhook for automatic publishing and reconciles version gaps. The FAQ also recommends fixing webhook problems before relying on resync alone.
- Open Settings → Webhooks on the GitHub repository.
- Leave exactly one active webhook whose payload URL is
https://registry.terraform.io/hooks/github. If several point there, delete the extras (the FAQ calls out duplicate hooks as a cause of publishing issues). - On registry.terraform.io, open the module → Manage Module → Resync Module. Wait for completion; avoid starting overlapping resyncs.
-
Confirm the hook: Open the webhook → Recent Deliveries on GitHub.
- Push a new semver tag and check that the new delivery succeeds (typically HTTP 200), then confirm the version on the module page, or
- Redeliver a failed delivery whose payload is still the tag push for the semver version you want. GitHub sends the same event body again; signatures use the webhook Secret as it is after your fixes, so this can publish that version without another tag. Use the delivery row that matches the correct tag ref.
Redeliver instead of a new tag
Yes — that is an acceptable approach when the semver tag already exists and the only problem was the webhook (for example signature failure after a bad secret edit). Redeliver is a normal GitHub feature for retrying a delivery; you are replaying the same push event the registry would have seen on a successful first attempt, not inventing a new release artifact in Git.
Prefer a new tag when you need a new module version anyway, when there is no failed delivery to replay (nothing reached GitHub’s hook list), or when you want a straight-line test from “tag push” to “delivery” without hunting history.
Prefer redeliver when bumping the version number would be artificial (the tag is already the release you mean) and you only need the registry to accept the same event again after fixing the hook.
If a single hook and resync do not restore publishing, contact registry support.
5. Configuration checks
Use these when deliveries succeed but versions still look wrong, or as routine verification:
-
Payload URL:
https://registry.terraform.io/hooks/github(HTTPS, that host, that path). -
Tags: Semantic version identifiers only, optional leading
v. Other ref names do not create registry versions. - Events: The hook must receive events for the activity that publishes versions (for example push events that include tag pushes). Overly narrow event filters can skip the tag you care about.
6. Summary: Copy-Paste
Push a new version tag when you prefer a fresh event (adjust remote and tag):
git tag v1.0.1
git push origin v1.0.1
Open repository webhooks (replace OWNER and REPO):
https://github.com/OWNER/REPO/settings/hooks
After opening the Terraform Registry webhook there, use Recent Deliveries → a failed row → Redeliver when you have already fixed the hook and want to retry the same tag event without pushing another tag.
7. Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| No new registry version after a tag push | Missing or failing webhook, duplicate hooks, or signature failure after a secret-only GitHub edit | One hook to registry.terraform.io/hooks/github, Resync Module, then push a new semver tag or Redeliver the failed delivery for that tag; re-check Recent Deliveries and the module page |
| Recent Deliveries show errors after changing Secret in GitHub | GitHub and registry no longer share the same secret | Dedupe hooks, Resync Module; if still failing, registry support |
| Delivery succeeds but no version | Invalid tag shape or delay | Fix tag to semver; wait; Resync if needed |
| Multiple registry webhooks | Stale or conflicting registrations | Delete duplicates, Resync per FAQ |
8. References
- Publish modules — naming, tags, Resync Module
- Terraform registry FAQ — Resync, duplicate webhooks, versions not appearing
- Validating webhook deliveries — GitHub signatures and the webhook secret
- Redeliver a delivery for a repository webhook — API equivalent of the Redeliver control in the delivery UI
Top comments (0)