fix: replace release-guard workflow with revert-latest job (#4838)

Also adds comments to:
- .goreleaser.yml: explains why make_release is set to false
- .github/workflows/release.yml: document release/artifact state at each step

.github/workflows/release-guard.yml

@@ -1,35 +0,0 @@
-name: Release Guard
-on:
-  release:
-    types: [created]
-
-permissions:
-  contents: write
-
-jobs:
-  unset-latest:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Restore previous release as latest if needed
-        run: |
-          LATEST_TAG=$(gh release list --json tagName,isLatest -q '.[] | select(.isLatest) | .tagName')
-          if [ "$LATEST_TAG" != "${{ github.event.release.tag_name }}" ]; then
-            echo "Release is not marked as latest (latest is $LATEST_TAG), skipping."
-            exit 0
-          fi
-
-          echo "Release ${{ github.event.release.tag_name }} is marked as latest, finding previous release..."
-
-          # Get the second release in the list (sorted by date, excluding drafts/prereleases by default)
-          # The first one is the current release, so we want the second one
-          PREVIOUS_TAG=$(gh release list --exclude-drafts --exclude-pre-releases --json tagName -q '.[1].tagName')
-
-          if [ -z "$PREVIOUS_TAG" ]; then
-            echo "No previous release found, cannot restore. Exiting."
-            exit 0
-          fi
-
-          echo "Restoring $PREVIOUS_TAG as latest..."
-          gh release edit "$PREVIOUS_TAG" --latest
-        env:
-          GH_TOKEN: ${{ github.token }}

.github/workflows/release.yml

@@ -16,6 +16,7 @@ jobs:
     env:
       DOCKER_CLI_EXPERIMENTAL: "enabled"
     steps:
+      # Setup steps - no external side effects.
       - name: Checkout
         uses: actions/checkout@v4
         with:
@@ -43,6 +44,25 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y upx
+
+      # GoReleaser pipeline (sequential, not atomic):
+      #   1. build + archive + checksum + sign  (local only, no side effects)
+      #   2. homebrew tap update                (commit to trufflesecurity/homebrew-trufflehog)
+      #   3. docker images + manifests          (DockerHub + GHCR, including :latest tags)
+      #   4. github release creation            (artifacts uploaded, make_latest: false)
+      #
+      # On failure: GoReleaser does not roll back completed phases. Depending
+      # on where it failed, some subset of the above may have been published.
+      # Check:
+      #   - Homebrew tap: https://github.com/trufflesecurity/homebrew-trufflehog
+      #   - DockerHub:    https://hub.docker.com/r/trufflesecurity/trufflehog/tags
+      #   - GHCR:         https://github.com/trufflesecurity/trufflehog/pkgs/container/trufflehog
+      #   - GH releases:  https://github.com/trufflesecurity/trufflehog/releases
+      #
+      # If the GitHub release was created but artifacts are missing, the
+      # install script (scripts/install.sh) will fail for users on that
+      # version. The release is NOT marked latest (make_latest: false), so
+      # /releases/latest still points to the previous good release.
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v6
         with:
@@ -53,7 +73,24 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
           GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}
+
+  # Promotes the GitHub release to "latest" only after the Release job fully
+  # succeeds (including post-steps). At this point, all artifacts have been
+  # published: Docker images and :latest tags are live, the Homebrew tap is
+  # updated, binaries are attached to the GitHub release, and checksums are
+  # signed.
+  #
+  # If this job fails, the release exists with all artifacts but is not flagged
+  # as latest. /releases/latest and scripts/install.sh still point to the
+  # previous release. To manually promote:
+  #   gh release edit <tag> --latest --repo trufflesecurity/trufflehog
+  mark-latest:
+    needs: Release
+    runs-on: ubuntu-latest
+    steps:
       - name: Mark release as latest
-        run: gh release edit ${{ github.ref_name }} --latest
+        run: gh release edit "$TAG" --latest
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}

.goreleaser.yml

@@ -1,5 +1,10 @@
 version: 2
 release:
+  # GoReleaser creates the GitHub release before artifacts finish uploading.
+  # scripts/install.sh queries /releases/latest to find the current version, so
+  # a premature "latest" flag causes install failures during the upload window.
+  # The release workflow's mark-latest job promotes the release only after
+  # GoReleaser completes successfully.
   make_latest: false
 builds:
   - id: trufflehog-upx