Skip to content

release_guidelines.md

Latest commit

 

History

History
193 lines (121 loc) · 37.6 KB

release_guidelines.md

File metadata and controls

193 lines (121 loc) · 37.6 KB

Releasing New Versions of the Power Platform Terraform Provider

Releasing a new version of the Power Platform Terraform Provider involves careful version management, automated builds/signing, and a final review before publishing. This guide breaks down the GitHub release workflow, the use of Changie for semantic versioning, the end-to-end release process, and best practices to ensure a secure and smooth release. Core maintainers can follow these steps and tips to confidently cut a new provider release.

Step-by-Step Release Process

Releasing a new version involves a sequence of steps that tie together Changie, git tagging, GitHub Actions, and Terraform Registry publication. Below is a step-by-step guide:

  1. Work on new branch

    git fetch origin
git checkout -b main origin/main
git pull origin main
git switch -c release/vNext

  2. Accumulate, Review, and Generate Changelog: As contributions are merged into main, ensure each user-facing change has a corresponding changelog entry or PR label denoting its impact (Breaking, Added, Fixed, etc.). When you decide to cut a release, review the .changes/unreleased fragments or PR labels to see what has accumulated for the next release. Then, run the Changie commands to generate a new section in CHANGELOG.md for the upcoming version, with all changes categorized. Open and review the CHANGELOG.md to ensure all notable changes are included and categorized correctly. This step is typically done in a final PR into main—commit the updated changelog (and any version bump in code if needed), get that PR approved and merged, and ensure main is ready for tagging.

    changie batch auto
changie merge

  3. Check in changes and create PR: After running the Changie commands, you'll have an updated CHANGELOG.md file with the new release entries. Commit these changes to your release branch and create a pull request targeting main. This PR should include:

    • The updated CHANGELOG.md with the new version section
    • Any version bumps in code files if applicable (e.g., provider version constants)
    • The removal of fragment files from .changes/unreleased/ (if Changie is configured to clean them up)
    git add CHANGELOG.md .changes/
git commit -m "chore: prepare changelog for release vNext"
git push origin release/vNext
# Create PR through GitHub UI or CLI targeting main branch

  4. Tag the Release in Git: After the PR is merged, working on main branch create a new Git tag for the version. The tag should start with v followed by the version number, for example v3.4.0 (the v prefix is required by Terraform conventions). From the command line, you can tag and push:

    git checkout main
git pull origin main
VERSION="v$(changie latest)"
git tag -a $VERSION -m "Release $VERSION" 
git push origin $VERSION

    Pushing the tag triggers the GitHub Actions release workflow.

  5. Automated Build and Release (GitHub Actions): Once the tag is pushed, the release.yml workflow detects the new version tag and begins executing. This workflow will set up a Go environment and run GoReleaser, which compiles the provider. No manual intervention is needed here; you can monitor the progress on the GitHub Actions page. GoReleaser will build binaries for all supported OS/arch, create the ProjectName_Version_SHA256SUMS file (with checksums of all binaries) and sign that file using the GPG key provided via secrets. The GPG key’s fingerprint is configured so that GoReleaser knows which key to use for signing the checksums. When GoReleaser finishes, it creates a draft release on GitHub named “v3.4.0” (populated with default release notes, which may just be a list of commits or an empty template) and uploads all the artifacts. According to the developer docs, the workflow “will detect the new tag and create a draft release” after the build completes . At this point, you should see a draft release in the GitHub repository’s Releases page, with assets like terraform-provider-powerplatform_3.4.0_windows_amd64.zip, etc., and the SHA256SUMS and its .sig file attached.

  6. Review the Draft Release: Before making the release public, take time to verify everything. Download a couple of the attached binaries (if you want) and run basic checks, or verify the checksums. Open the draft release notes – by default, GoReleaser might have populated them using commit messages (because the config uses changelog: use: github-native) or it might be blank. You should replace or edit this description with the curated changelog you generated. An easy way is to copy the relevant section from CHANGELOG.md (which Changie just created for 3.4.0) into the release notes field. This ensures the release notes are human-friendly and comprehensive. Double-check that the version number is correct (no typos in tag or title), and that all expected changes are listed. Also verify that the assets list looks complete (e.g., all OS builds are present, the manifest JSON is attached, etc.). This review acts as a quality control checkpoint so that any issues can be caught before users see the release.

  7. Publish the Release on GitHub: Once satisfied with the draft, hit the “Publish release” button on GitHub. This will take the release out of draft status and officially publish version 3.4.0 on GitHub. At this moment, the release becomes visible to the public and the GitHub webhook will notify the Terraform Registry of the new version. (If for some reason you realize something is wrong before publishing, you can delete or edit the draft and even delete the tag if you must start over – see Troubleshooting below.)

  8. Terraform Registry Ingestion: Publishing the release triggers the pre-configured webhook to Terraform Registry. The registry receives an event that version v3.4.0 was released, and it reaches out to GitHub to fetch the release artifacts. The registry will find the provider binaries and the signed checksums, and then verify the signature using the public key you uploaded in the Terraform Registry settings (during initial setup). If everything is in order, the new version will be listed on the Terraform Registry under the provider’s page. Within a few minutes, you should see version 3.4.0 appear on the registry (you can check registry.terraform.io/providers/microsoft/power-platform for the list of versions). At this point, users can download the new version by specifying it in their Terraform configuration or by running terraform init (Terraform will automatically find the latest version unless it’s a prerelease). Note: Prerelease versions (like those with “-preview”) will not be selected by default; a user must explicitly require that version, as per SemVer rules.

  9. Post-release tasks: Announce the new release (if you have a mailing list or GitHub discussion for releases). Monitor for any unexpected issues. It’s good practice to try a quick terraform init with the new provider to ensure installation works. Also, tag the documentation if needed (for example, if using a separate docs site repo). Most of the heavy lifting is automated, so ideally at this point the provider version is live and documented via the changelog.

By following these steps, releasing a new version becomes a repeatable process. The key triggers are the git tag (to start automation) and the Publish action (to finalize and notify the registry). Everything in between is handled by automation, with you supervising.

GitHub Release Workflow Overview (release.yml)

The provider’s release is automated via a GitHub Actions workflow defined in .github/workflows/release.yml. This workflow’s purpose is to build the provider binaries for all supported platforms, create a release on GitHub with those assets, and prepare the release for Terraform Registry publication. It is structured according to HashiCorp’s recommended template for Terraform providers, meaning it triggers whenever a new Git tag matching a semantic version (e.g. v1.2.3 or v1.2.3-preview) is pushed to the repository.

Workflow Steps: Once a version tag is pushed, the release workflow kicks in automatically. Key steps include:

  • Building Artifacts: The workflow uses GoReleaser to compile the provider for multiple OS and architecture combinations. For example, Linux, Windows, and macOS binaries are produced for x86_64 and other supported architectures. This ensures users on different platforms can download the provider.
  • Generating Checksums: GoReleaser aggregates all binary checksums into a SHA256SUMS file. This file is crucial for verifying integrity of downloads.
  • Signing the Release: The workflow signs the checksums (and/or other artifacts) with a GPG key to meet Terraform Registry security requirements. The maintainers have configured secret variables (GPG_PRIVATE_KEY and PASSPHRASE) in the repo’s settings to provide the GPG key for signing. During the workflow, GoReleaser uses these to produce a detached GPG signature for the checksums, ensuring the release can be cryptographically verified. All provider releases must be signed with a trusted GPG key – the registry will later verify the signature against the public key you’ve uploaded.
  • Attaching Assets and Drafting a Release: The workflow then creates a GitHub Release (in draft mode) and uploads the compiled binaries, the SHA256SUMS file, the signature, and any extra metadata (like a terraform-registry-manifest.json) to that release. By default, the release is kept unpublished (draft). This draft status is intentional for review – no one outside maintainers can see it yet, and Terraform Registry isn’t notified until the release is published.

Interaction with Terraform Registry: The Terraform Registry is indirectly updated through this process. After the GitHub release is reviewed and published (see next sections), a webhook automatically notifies the Terraform Registry of the new provider version. Specifically, when the release is published, GitHub’s webhook (set up when the provider was first registered on the Terraform Registry) triggers a registry ingress of the new version. The registry then fetches the release assets from GitHub, verifies the GPG signature against the public key on file, and adds the new version to the provider’s listing. In short, the GitHub release workflow handles building and signing, and the Terraform Registry picks up the finished release via webhook – no manual upload to the registry is needed.

Semantic Versioning and Changie

This project follows semantic versioning (SemVer) for releases. In summary, that means:

  • MAJOR version increments for breaking changes or incompatible API changes,
  • MINOR for new features added in a backward-compatible way,
  • PATCH for backward-compatible bug fixes.
  • SUFFIX if a release is a preview or prerelease, a hyphen and label are added (e.g. v1.0.0-preview), which Terraform treats as a prerelease version (not selected as latest by default). The -preview suffix was used for early development of the provider and is not used anymore. The -prerelease has not been used yet but it could be used in the future to allow users to test upcoming functionality before committing to a normal release.

To manage this consistently, the maintainers use a tool called Changie for changelogs and version bump suggestions. The configuration in .changie.yaml defines categories (or “kinds”) of changes and ties them to SemVer significance. For example, changes labeled “Breaking” will automatically suggest a major version bump, whereas an “✨ Added” feature or other “Changed” enhancement implies a minor bump. Fixes, security patches, or documentation updates are considered patch changes. These categories correspond to labels or annotations on pull requests and changelog fragments:

  • Breaking – major (incompatible change)
  • ✨ Added/Changed/Deprecated – minor (new functionality or deprecations)
  • ️Removed – major (a removed feature is breaking)
  • Fixed / Security / Documentation – patch (bug fixes or non-functional changes)

Using Changie, maintainers (and contributors) include a small changelog snippet for each PR under a directory (by default, .changes/unreleased). Each snippet is annotated with the type of change (kind) and the issue/PR number. For instance, a PR that adds a new resource might include an entry marked as “Added” with the PR number. Changie keeps these change files until release time.

How PRs should be marked: Contributors should label their pull requests with the appropriate change category or include the corresponding changelog fragment. This ensures the change is documented and that the next release’s version number will be chosen correctly. The .changie.yaml config uses these labels to decide how to increment the version. For example, if any PR since the last release was labeled Breaking, the next version will be a new major version. If there’s no breaking change but there are new features labeled Added, it will be a minor bump; otherwise, for only fixes, it will be a patch bump. Maintainers should enforce this in code review: every PR that changes behavior should either be labeled or accompanied by a changelog entry indicating its type.

Generating the Changelog: Right before a release, the maintainer will run Changie’s batch command to compile these fragments into the main CHANGELOG.md. According to the developer guide, as the final PR before a release, you should “create documentation using Changie” with a command like:

changie batch auto
changie merge

Changie will gather all files in .changes/unreleased, group them under headings (Added, Fixed, etc.), and append a new section in CHANGELOG.md for the new version (with today’s date) containing all the changes. It then clears the unreleased folder (often moving those files into a versioned folder or marking them as released). The result is a nicely formatted changelog entry for the new version, adhering to the “Keep a Changelog” style and including references to issue/PR numbers. This step not only produces user-facing release notes, but also double-checks that the version number aligns with the content. The updated CHANGELOG.md is committed to main before tagging the release.

In summary, Changie ensures every change is accounted for and categorized. Maintainers should make sure PR titles or labels reflect the change type (to ease writing the fragment), and that the fragments are properly added. By doing so, the version bump is predictable and follows Semantic Versioning rules, and the generated changelog clearly communicates what’s in the release.

Security, Automation, and Quality Safeguards in the Workflow

The release workflow is designed with security and quality in mind:

  • GPG Signature for Trust: As mentioned, every release is GPG-signed. HashiCorp requires this to ensure that consumers of the provider can verify its authenticity. The public key corresponding to the signing key is added to the Terraform Registry once (when setting up the provider account), and the registry rejects any release that isn’t signed by that key. Terraform CLI also verifies the plugin’s signature during terraform init for an extra layer of trust. Maintainers must keep the GPG private key secure and update the registry if the key changes. Using GitHub Secrets to store the key material (in GPG_PRIVATE_KEY etc.) means the private key is not exposed in the repo, and the workflow has access to it only at build time.

  • Automated Build and Release (CI/CD): The use of GitHub Actions and GoReleaser greatly improves efficiency and consistency. Instead of manually building binaries for each OS or risking human error in packaging, the workflow compiles and packages everything in one go. It uses a tested configuration (the HashiCorp scaffolding) that ensures the release assets meet the Terraform Registry’s expectations. This includes naming conventions and attaching a special manifest (which helps the registry know which provider and version the release is for). Automation also means that if you follow the process (updating changelogs, tagging, etc.), the output is predictable and standardized. This reduces the chance of missing an artifact or forgetting a step.

  • Draft Release for Human Review: One deliberate quality-control measure is keeping the GitHub release as a draft until a maintainer approves it. This prevents a situation where a mis-tagged or mis-built release immediately goes public. The maintainer can inspect the release notes and artifacts and compare them against the expected changelog. Only after this review do they manually publish the release. This step ensures that even with heavy automation, there is a final sanity check by a human, catching issues like a missing binary, incorrect version name, or mistakes in the changelog.

  • Separation of Duties and Security: The workflow runs in the context of GitHub Actions with limited permissions. Typically, the workflow uses the repository’s GITHUB_TOKEN (which by default has permission to create releases in the same repo) to upload assets. Because the release process is triggered by a tag push, and generally only maintainers can push tags to the main repo, it ensures that only authorized persons can initiate a release. The HashiCorp template workflow also recommends restricting which external actions can run (for example, only allowing the known GoReleaser action), which mitigates supply chain risks. All secrets (like the GPG key) are scoped to the repository and not exposed elsewhere.

  • Testing and Validation: While the release workflow itself doesn’t run the test suite (its job is to package and release), the project has other workflows (e.g., run_tests.yml) that run on every pull request and on the main branch. Maintainers should ensure those tests are passing before even thinking about a release. By the time we tag a release, the code has been through unit tests and acceptance tests in CI. This approach means the release workflow is dealing with already-validated code, focusing on build/packaging. In addition, the release workflow could include a final verification step (some projects run a quick integration test or at least terraform version on the built provider) as an extra safety net. If any required check fails, the GitHub Action will abort and no release will be created.

  • Semantic Versioning Discipline: The use of Changie and labeling ensures that version numbers aren’t chosen arbitrarily. This enforces a level of quality control regarding API stability. For example, if a breaking change sneaks in but a maintainer forgets, the presence of a “Breaking” label or fragment will signal that a major version bump is needed. Adhering to SemVer is important for user trust – consumers can upgrade patch/minor versions confidently for fixes and new features, knowing that breaking changes will only come in a major version (which they can plan for). The project explicitly follows SemVer to mitigate issues when changes are introduced. By documenting this and sticking to it, maintainers preserve compatibility promises.

  • Following HashiCorp Guidelines: The workflow and processes in this project largely follow HashiCorp’s official guidance for publishing providers. This means the maintainers benefit from community best practices and updates. For instance, the HashiCorp documentation suggests not to modify an existing release – if there’s a mistake, create a new version rather than reusing a tag. The team abides by this, ensuring once something is released, it’s immutable (this avoids users encountering checksum mismatches). Such guidance, plus use of HashiCorp’s verified action templates, contributes to the security and reliability of the release process.

In essence, the release pipeline automates the tedious parts (build/sign/upload) and builds in safeguards (signatures, draft review, testing gates) to maintain a high-quality output. Maintainers should remain vigilant (especially during the review step), but can rely on the automation to do the heavy lifting correctly.

Best Practices for Maintainers

To keep the release process smooth and trouble-free, core maintainers should consider the following best practices:

  • Plan Versions and Changes: Regularly triage incoming changes and determine what the next version should be. If multiple breaking changes are queued, you might batch them into one major release. For a series of small improvements, a minor release makes sense. Communicate in advance if a major version (with breaking changes) is upcoming, so contributors know to target the correct branch or timing.

  • Enforce Changelog Entries: Every user-facing change should have a changelog fragment (or at least a clear PR description) before merging. This discipline means you won’t scramble to write release notes at the last minute. It also feeds Changie the info it needs. The project’s contributing guidelines should mention this (and if not, consider updating them). Common practice is to have PR templates reminding contributors to add a .changes/unreleased file with their change description and issue number.

  • Use Meaningful Labels: Apply the standardized labels (Added, Fixed, Breaking, etc.) to PRs consistently. This not only helps Changie but also lets everyone see the nature of changes at a glance. It can also trigger any “semantic PR” checks if set up (ensuring PR titles follow Conventional Commits or similar). The labels defined in .changie.yaml should exist in the repo’s labels list – ensure they do, so maintainers can use them when merging external contributions.

  • Keep main in a Releasable State: Try to avoid partially done features or unstable code in the main branch. Since releases are cut from main, it’s wise to merge feature toggles or experimental code only when it’s not going to harm users. If something is merged but not ready for release, you can mark it as such (perhaps with a “do not release” note), but a cleaner approach is to use feature flags or wait until completion. This way, you can tag a release from main at almost any time with confidence that tests pass and features are complete.

  • Run Tests Before Tagging: Double-check that CI is green on the commit you’re about to tag. If needed, run the test suite locally or trigger the run_tests workflow on the latest main commit. While this seems obvious, it’s easy to tag a release after merging a last PR without waiting for CI – avoid that temptation. A passing build on main is your safety net.

  • Match Tag and Changelog: When running changie batch, you typically supply the intended version. Ensure the git tag you push exactly matches that version (including -preview if present). For example, if changelog says “## 4.0.0 - 2025-05-01”, the tag must be v4.0.0. Typos or mismatches will confuse users and possibly the registry. If a mistake is made, it’s better to fix and tag a new version (e.g. if you accidentally tagged v4.0.0 but meant 3.4.0, you'd need to delete the wrong tag and possibly do a 3.4.1 if 3.4.0 was already taken).

  • Use Annotated Tags: Always create annotated tags (with a message) rather than lightweight tags. Annotated tags are recommended for releases as they get recorded in Git history with a date and message (and GPG signable if desired). The examples above with -a flag ensure this.

  • Monitor the Workflow: After pushing the tag, watch the GitHub Actions run (Actions tab -> the release workflow run). It’s important to catch any errors. If it fails (perhaps due to a transient issue or misconfiguration), you’ll need to address that and possibly retag (see Troubleshooting below). If it succeeds, check that it indeed created a draft release on the GitHub Releases page.

  • Review Before Publishing: Do not skip the draft review. Compare the draft release notes with your CHANGELOG.md. If something significant is missing from the notes, you may have forgotten a fragment – you can still edit the release notes manually to include it (and later correct the process for next time). Also verify the binary names – they should follow the pattern terraform-provider-powerplatform_VERSION_OS_ARCH.zip. If one of them is misnamed or missing, it could indicate a problem in the build matrix. It’s rare if the config is correct, but it’s worth a look.

  • Publish During Work Hours: It’s wise to publish a release at a time when you (and possibly other maintainers) are available to monitor the aftermath. In case something goes wrong (for example, a critical bug was missed), you can respond quickly (perhaps by yanking the release or issuing a fix). Also, Terraform Registry publication is almost instantaneous via webhook, but if the webhook fails you might need to manually nudge it – doing this while you’re around is easier.

  • Communicate Major Changes: If the new release is a major version or contains breaking changes, consider highlighting these in the release notes (and maybe in the project README or docs). Even though SemVer and the changelog entry indicate breaking changes, calling them out explicitly (e.g., “Breaking: Changed authentication method, see upgrade guide”) is good practice. This helps users upgrade smoothly and maintains goodwill.

  • Never Modify Published Releases: Once a release is published and picked up by the registry, do not modify it. If you find an issue, you must create a new version. HashiCorp’s documentation explicitly warns against changing release assets after the fact, as it will cause checksum verification errors for users. Even if it’s a small fix, bump the version (patch bump) and go through the release process again. The Terraform Registry doesn’t allow deleting a version either, so you can’t “undo” a release – you can only supersede it with a new one. Keep this in mind before hitting publish.

  • Maintain the GPG Key: The signing key is critical. If the key were to expire or be revoked, you’d need to add a new one to the registry. Plan ahead for key rotations (the Terraform Registry allows adding multiple public keys, so you can transition if needed). Make sure the GPG_FINGERPRINT env var in the workflow is updated if you change keys. Also, restrict access to the GPG private key – only trusted maintainers should have the ability to push a release (since they essentially have access to use the signing key via GitHub Actions).

  • Follow HashiCorp Updates: The Terraform provider ecosystem may evolve (for example, new required fields in the manifest, updated signing processes, etc.). Keep an eye on the official HashiCorp docs or announcements. Since this provider’s release process is based on the standard scaffold, updating your .goreleaser.yml or workflow to match the latest template can be beneficial. For instance, HashiCorp now provides a reusable GitHub Action workflow for releases – the team could consider adopting that to reduce maintenance overhead on your own workflow file. Always test changes to the release process in a dry run (perhaps by releasing a "-preview" version) to confirm nothing is broken.

By adhering to these best practices, maintainers can ensure each release is predictable, secure, and of high quality. Now, let’s look at what to do when things don’t go as planned.

Troubleshooting Common Release Pipeline Issues

Even with a solid process, you may encounter occasional issues. Here are some common problems and how to address them:

  • GitHub Action Didn’t Trigger: After pushing a tag, if the release workflow did not start, confirm that the tag matches the pattern. The workflow triggers on tags like v*. Tags missing the v (e.g., 3.4.0 instead of v3.4.0) or tags with additional text (like v3.4 without patch number) might be ignored as they’re not valid SemVer. Also ensure there isn’t a branch with the same name as the tag, which can prevent the tag event. If you discover a mistake, retag correctly: delete the wrong tag (git push origin :refs/tags/<tagname> to remove it from GitHub) and push a properly named tag. Lastly, check repository settings under Actions – the workflow file should exist on the default branch and Actions should be enabled for tag events (most likely yes, if other workflows run).

  • Workflow Fails Mid-run: If the GitHub Action started but failed (red X in the Actions log), inspect the log output to pinpoint why. Common issues:

    • GoReleaser configuration errors: Perhaps the goreleaser config has a syntax issue or a reference to a file that doesn’t exist. Fix the config (.goreleaser.yml) as needed and push a new tag (you’ll need to increment the version, e.g., v3.4.1, because v3.4.0 was already used even if incomplete).
    • Missing Secrets or Permissions: A failure during signing could mean the GPG secrets weren’t available. Ensure GPG_PRIVATE_KEY and PASSPHRASE are set in the GitHub repo Secrets (or Actions variables) and that the workflow is referencing them correctly. Also verify the GPG_FINGERPRINT environment variable is set (often via repository or organization secret) to match your key’s fingerprint. If the error says “no secret key” or similar, the Actions runner couldn’t find/import your key – double-check the format of the secret (it should be an ASCII-armored private key block).
    • Network or external issues: Sometimes downloading Go modules or dependencies can fail due to a network hiccup. Usually rerunning the job will solve transient issues. You can re-run the failed workflow from the Actions interface. However, be careful: if the workflow is triggered by a tag and you re-run without changing anything, it will attempt to create the release again. Since the draft release might already exist, it could either overwrite or fail. It’s often cleaner to delete the draft release and the tag, then re-tag with a bumped patch number to retry fresh.
    • Test Failures: If you (optionally) integrate tests in the release job or if you run some final validation that fails, treat it like any CI failure – fix the code or tests on main and then create a new tag for a new version that includes the fix. Never force push a new commit onto an existing tag; always go forward with a new version number.

  • Draft Release Looks Wrong: If the workflow succeeded but the draft release content is not as expected (e.g., missing files or incorrect info):

    • If a binary is missing, check .goreleaser.yml to ensure that platform is included. For instance, if Darwin/arm64 was not built, maybe the GoReleaser build section lacks darwin or that GOOS in the matrix. Update the config and prepare to do a new release. If you need that missing binary for this version, you’ll have to build a new version (since you can’t edit the existing one’s assets reliably).
    • If the release notes (changelog) are empty or just a list of commits but you expected the nicely formatted notes from Changie, remember that GoReleaser’s github-native changelog just uses commit history by default. It’s not an error per se – you need to manually paste the curated notes. In the future, you could automate this by having the workflow read from CHANGELOG.md for the version, but it’s also fine to do it manually. Edit the draft and paste the missing text.
    • If the version number in the draft title is wrong (say you tagged v3.5.0 but the release is titled v3.4.0 due to a mistake in tag), don’t publish it. It’s better to delete that draft and tag, fix whatever version confusion happened, and start again (with the correct version tag). Consistency is key for user clarity.

  • Terraform Registry Didn’t List the Release: After publishing on GitHub, usually within a minute the version shows up on registry. If it doesn’t:

    • Go to your Terraform Registry Provider settings (you must be an admin of the organization on registry.terraform.io). Check if a webhook delivery failed. The HashiCorp docs note that a webhook is created on your repo to watch for releases. If that webhook was accidentally removed or is malfunctioning, you can use the Resync function: remove any existing registry.terraform.io webhook from the GitHub repo, then in the Terraform Registry settings for the provider, click “Resync”. This will set up a fresh webhook. Then, you can trigger it by re-publishing the release (even editing and re-saving might trigger, or worst case, delete and re-create the release).
    • If the webhook is fine but the release was not ingested, ensure you did mark the release as “Latest” (which happens automatically when publishing a non-prerelease on GitHub). The registry ignores drafts and prereleases unless explicitly requested. For a prerelease (like vX.Y.Z-beta or -preview), you actually have to publish it on GitHub (still as a prerelease flag). Terraform Registry will index it but not show it as the default. In the registry UI, you might need to toggle “Include prereleases” to see it.
    • Check that the release assets include the checksum file and the signature. The registry needs the SHA256SUMS and the .sig in order to verify the release. If those were missing, the registry might refuse to add the version. In such a case, fix your workflow to include and sign checksums (the scaffold does this by default) and issue a new version.
    • If you see an error in Terraform Registry (e.g., “invalid signature” or “No GPG key found”), it means the registry could not verify the GPG signature. Ensure the public key was uploaded in the Terraform Registry’s signing keys section for your namespace. Also ensure the release was signed by the correct private key (matching that public key). You can verify by running gpg --verify on the .sig file with your public key locally. If the key was wrong (e.g., you have multiple keys and the wrong one was used), update the GPG_FINGERPRINT env var to the correct key and make a new release.

  • Users Report Checksum Mismatch: This is a serious issue that typically means the release was altered after the registry indexed it (or there’s an attack, but likely the former). If someone does terraform init and gets a checksum error for your provider version, it could be because an asset was re-uploaded or changed. Remember, you should never modify a published release’s assets. To resolve this, you must create a new release. For example, if v3.4.0 is bad, fix whatever problem (ensuring the files won’t change next time) and release v3.4.1. Communicate in the release notes what was fixed. Mark the v3.4.0 release as obsolete (you might edit its description to say “replaced by v3.4.1 due to a packaging issue” or similar). This maintains the trust and the integrity of what’s on the registry.

  • Accidentally Published Too Early: If you hit “Publish” on the release on GitHub but then realize something’s wrong (maybe you forgot to include a change, or the version was mis-numbered), you cannot fully undo it. Once the registry has it, that version number is effectively taken. You have a few options:

    • If the issue is minor (like release notes text), you can edit the GitHub release notes after publishing – that won’t affect the registry (which only cares about the binaries and checksums). If it’s documentation, just fix it and maybe add a note.
    • If the issue is in the code or binaries (e.g., a bug or you tagged wrong code), the only real solution is to fix the code and issue a new version. You might yank the bad release by marking it as a pre-release in GitHub (so it’s less visible) or by clearly noting it’s not valid. But you can’t remove it from the registry. Increment the version appropriately (if nothing worked in that release, you could use the same version number with a -fix prerelease tag for testing, but ultimately you’ll need a new proper version). It’s better to treat the mistaken release as a lesson and move on with a higher version. For example, if v5.0.0 went out broken, publish a v5.0.1 quickly with the fix.
    • Internally, discuss what went wrong in the process to cause this. Maybe add an extra manual check before tagging or improve test coverage. The goal is to minimize these post-publish fixes.

  • Major Release Considerations: When doing a major version (like v4.0.0 -> v5.0.0), there are additional checks. Ensure any breaking changes are well-documented. If state migration functions are needed (in Terraform schema) for smooth upgrades, ensure they are in place before release. Major releases can also involve updating documentation links (if the doc site uses versioned paths). It’s good to run terraform init with the new major version on some real configurations to see if it requires any manual state or config changes that weren’t anticipated. Essentially, test the upgrade path for users.

Finally, remember that the Terraform Registry’s support can help if you face publishing issues that you cannot resolve. You can reach out to HashiCorp (terraform-registry support) if a release is stuck or something odd is happening with your provider listing.

By following this guide and being mindful of these troubleshooting tips, you’ll be able to manage the Power Platform provider’s releases in a secure, automated, and predictable way. Each release will have a clear history of what changed, aligned with semantic versioning, and delivered to users via the Terraform Registry with minimal friction. Happy releasing!