fix(mdm): update release flow

shubham-stepsecurity · shubham-stepsecurity · commit 3cbd1f0efa3b · 2026-04-08T20:15:15.000+05:30
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -68,10 +68,21 @@ jobs:
       - name: Install cosign
         uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
 
+      - name: Locate binary
+        id: binary
+        run: |
+          BINARY=$(find dist -type f -name '*darwin_unnotarized' | head -1)
+          if [ -z "$BINARY" ] || [ ! -f "$BINARY" ]; then
+            echo "::error::Binary not found"
+            find dist -type f
+            exit 1
+          fi
+          echo "path=$BINARY" >> "$GITHUB_OUTPUT"
+
       - name: Sign artifacts with Sigstore
         run: |
-          ARCHIVE=$(find dist -name 'stepsecurity-dev-machine-guard-*-darwin.tar.gz' | head -1)
-          cosign sign-blob "$ARCHIVE" --bundle "${ARCHIVE}.bundle" --yes
+          cosign sign-blob "${{ steps.binary.outputs.path }}" \
+            --bundle "${{ steps.binary.outputs.path }}.bundle" --yes
           cosign sign-blob stepsecurity-dev-machine-guard.sh \
             --bundle dist/stepsecurity-dev-machine-guard.sh.bundle --yes
 
@@ -80,13 +91,13 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           gh release upload "${{ steps.version.outputs.tag }}" \
-            dist/stepsecurity-dev-machine-guard-*-darwin.tar.gz.bundle \
+            "${{ steps.binary.outputs.path }}.bundle" \
             dist/stepsecurity-dev-machine-guard.sh.bundle \
             --clobber
 
       - name: Attest build provenance
         uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
         with:
           subject-path: |
-            dist/stepsecurity-dev-machine-guard-*-darwin.tar.gz
+            ${{ steps.binary.outputs.path }}
             stepsecurity-dev-machine-guard.sh
diff --git a/.goreleaser.yml b/.goreleaser.yml
@@ -26,16 +26,14 @@ universal_binaries:
     ids:
       - stepsecurity-dev-machine-guard
     replace: true
-    name_template: stepsecurity-dev-machine-guard
+    name_template: "stepsecurity-dev-machine-guard-{{ .Version }}-darwin_unnotarized"
 
 archives:
-  - id: archive
-    ids:
+  - ids:
       - universal
     formats:
-      - tar.gz
-    strip_binary_directory: true
-    name_template: "stepsecurity-dev-machine-guard-{{ .Version }}-darwin"
+      - binary
+    name_template: "stepsecurity-dev-machine-guard-{{ .Version }}-darwin_unnotarized"
 
 release:
   draft: true
diff --git a/docs/release-process.md b/docs/release-process.md
@@ -1,23 +1,19 @@
 # StepSecurity Dev Machine Guard — Release Process
 
-This document describes how releases are created, signed, and verified.
+This document describes how releases are created, signed, notarized, and verified.
 
 > Back to [README](../README.md) | See also: [CHANGELOG](../CHANGELOG.md) | [Versioning](../VERSIONING.md)
 
 ---
 
 ## Overview
 
-Releases are created via a manually triggered GitHub Actions workflow (`workflow_dispatch`) that requires approval from the `release` environment. The workflow uses [GoReleaser](https://goreleaser.com/) to:
+Releases are a two-phase process:
 
-1. Read the version from `internal/buildinfo/version.go` (`const Version = "1.9.0"`)
-2. Verify the tag does not already exist (immutability)
-3. Build platform-specific binaries with GoReleaser
-4. Sign the binaries with [Sigstore](https://www.sigstore.dev/) cosign (keyless)
-5. Generate SHA256 checksums
-6. Create a Git tag and GitHub Release
-7. Attach binaries, Sigstore bundles, and checksums as release assets
-8. Generate SLSA build provenance attestation
+1. **CI (automated)** — GitHub Actions builds the universal macOS binary, signs it with Sigstore, and creates a **draft** release with the binary named `stepsecurity-dev-machine-guard-VERSION-darwin_unnotarized`.
+2. **Apple notarization (manual)** — Download the binary, sign and notarize it with an Apple Developer account, upload the notarized binary to the draft release, and publish.
+
+---
 
 ## How to Create a Release
 
@@ -26,109 +22,110 @@ Releases are created via a manually triggered GitHub Actions workflow (`workflow
 Update `Version` in `internal/buildinfo/version.go`:
 
 ```go
-const Version = "1.9.0"
+const Version = "1.9.1"
 ```
 
-Update the [CHANGELOG.md](../CHANGELOG.md) with a new section for the version.
-
-Commit and push to `main`.
+Update [CHANGELOG.md](../CHANGELOG.md). Commit and push to `main`.
 
 ### 2. Trigger the release workflow
 
 1. Go to [Actions > Release](https://github.com/step-security/dev-machine-guard/actions/workflows/release.yml)
-2. Click **Run workflow**
-3. Select the `main` branch
-4. Click **Run workflow**
+2. Click **Run workflow** on the `main` branch
 
-### 3. Approve the release
+The workflow will:
+- Create a git tag (`v1.9.1`)
+- Build a universal macOS binary (amd64 + arm64) via GoReleaser
+- Sign with Sigstore cosign (keyless)
+- Upload as `stepsecurity-dev-machine-guard-VERSION-darwin_unnotarized` to a **draft** release
+- Record the SHA256 of the unnotarized binary in the release notes
+- Generate SLSA build provenance attestation
 
-The workflow uses a GitHub Environment called `release` that requires approval. A designated reviewer must approve the run before it proceeds.
+### 3. Apple notarization (manual)
 
-### 4. Verify the release
+On a Mac with the Apple Developer certificate installed:
 
-Once approved, the workflow will create the tag, build the binaries, sign them, create the GitHub Release, and upload the artifacts. Check the [Releases page](https://github.com/step-security/dev-machine-guard/releases) to confirm.
+```bash
+VERSION="1.9.1"
 
----
+# Download the unnotarized binary
+gh release download "v${VERSION}" --repo step-security/dev-machine-guard \
+  --pattern "stepsecurity-dev-machine-guard-${VERSION}-darwin_unnotarized"
 
-## Release Artifacts
+# Rename for signing
+cp "stepsecurity-dev-machine-guard-${VERSION}-darwin_unnotarized" \
+   "stepsecurity-dev-machine-guard-${VERSION}-darwin"
 
-Each release includes the following artifacts:
+# Sign with Apple Developer ID
+codesign --sign "Developer ID Application: <COMPANY> (<TEAM_ID>)" \
+  --options runtime --timestamp "stepsecurity-dev-machine-guard-${VERSION}-darwin"
 
-| Artifact | Description |
-|----------|-------------|
-| `stepsecurity-dev-machine-guard_darwin_amd64` | macOS Intel binary |
-| `stepsecurity-dev-machine-guard_darwin_arm64` | macOS Apple Silicon binary |
-| `checksums.txt` | SHA256 checksums of all release artifacts |
-| `*.bundle` | Sigstore cosign bundles (signature, certificate, and Rekor transparency log entry) |
+# Notarize with Apple (~5 min)
+xcrun notarytool submit "stepsecurity-dev-machine-guard-${VERSION}-darwin" \
+  --apple-id <APPLE_ID_EMAIL> --team-id <TEAM_ID> \
+  --password <APP_SPECIFIC_PASSWORD> --wait
 
----
-
-## Verifying a Release
-
-Anyone can verify the authenticity of a release artifact using [cosign](https://docs.sigstore.dev/cosign/system_config/installation/).
+# Upload the notarized binary to the draft release
+gh release upload "v${VERSION}" "stepsecurity-dev-machine-guard-${VERSION}-darwin" \
+  --repo step-security/dev-machine-guard
+```
 
-### Install cosign
+### 4. Publish the release
 
 ```bash
-# macOS
-brew install cosign
-
-# Other platforms: https://docs.sigstore.dev/cosign/system_config/installation/
+gh release edit "v${VERSION}" --repo step-security/dev-machine-guard \
+  --draft=false --latest
 ```
 
-### Verify the binary signature
+---
 
-```bash
-# Download the release artifacts
-gh release download v1.9.0 --repo step-security/dev-machine-guard
-
-# Verify the Sigstore signature (example for Apple Silicon)
-cosign verify-blob stepsecurity-dev-machine-guard_darwin_arm64 \
-  --bundle stepsecurity-dev-machine-guard_darwin_arm64.bundle \
-  --certificate-identity-regexp "github.com/step-security/dev-machine-guard" \
-  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"
-```
+## Release Artifacts
 
-A successful verification confirms:
+Each release includes:
 
-- The binary was signed by the `step-security/dev-machine-guard` GitHub Actions workflow
-- The signature is recorded in the [Rekor transparency log](https://search.sigstore.dev/)
-- The binary has not been tampered with since signing
+| Artifact | Description |
+|----------|-------------|
+| `stepsecurity-dev-machine-guard-VERSION-darwin` | Notarized universal macOS binary (amd64 + arm64) |
+| `stepsecurity-dev-machine-guard-VERSION-darwin_unnotarized` | Original CI-built binary (for provenance verification) |
+| `stepsecurity-dev-machine-guard-VERSION-darwin_unnotarized.bundle` | Sigstore cosign bundle for the unnotarized binary |
+| `stepsecurity-dev-machine-guard.sh` | Legacy shell script |
+| `stepsecurity-dev-machine-guard.sh.bundle` | Sigstore cosign bundle for the shell script |
 
-### Verify the checksum
+---
 
-```bash
-sha256sum -c checksums.txt
-```
+## Verifying a Release
 
-### Verify build provenance
+### Verify a release
 
 ```bash
-gh attestation verify stepsecurity-dev-machine-guard_darwin_arm64 \
-  --repo step-security/dev-machine-guard
-```
+VERSION="1.9.1"
 
----
+# Download release artifacts
+gh release download "v${VERSION}" --repo step-security/dev-machine-guard \
+  --pattern "stepsecurity-dev-machine-guard-${VERSION}-darwin*"
 
-## Immutability Guarantees
+# Verify Apple signature and notarization
+codesign --verify --deep --strict "stepsecurity-dev-machine-guard-${VERSION}-darwin"
+spctl --assess --type execute "stepsecurity-dev-machine-guard-${VERSION}-darwin"
 
-Releases are designed to be immutable through multiple layers:
+# Verify Sigstore signature on the unnotarized binary
+cosign verify-blob "stepsecurity-dev-machine-guard-${VERSION}-darwin_unnotarized" \
+  --bundle "stepsecurity-dev-machine-guard-${VERSION}-darwin_unnotarized.bundle" \
+  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+  --certificate-identity-regexp "github.com/.*/dev-machine-guard"
 
-1. **Tag protection** — configure [tag protection rules](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules) in repository settings to prevent tag deletion or overwriting.
-2. **Duplicate tag check** — the release workflow fails if the tag already exists, preventing accidental re-releases of the same version.
-3. **Sigstore transparency log** — every signature is recorded in the public [Rekor](https://rekor.sigstore.dev/) transparency log. Even if an artifact were replaced, verification against the original log entry would fail.
-4. **SLSA build provenance** — the attestation links the artifact to the exact workflow run, commit SHA, and build environment.
+# Verify build provenance
+gh attestation verify "stepsecurity-dev-machine-guard-${VERSION}-darwin_unnotarized" \
+  --repo step-security/dev-machine-guard
+```
 
 ---
 
-## Environment Setup
-
-The release workflow requires a GitHub Environment named `release` with required reviewers. To configure:
+## Immutability Guarantees
 
-1. Go to **Settings > Environments** in the repository
-2. Create an environment named `release`
-3. Enable **Required reviewers** and add the appropriate team members
-4. Optionally restrict to the `main` branch under **Deployment branches**
+1. **Draft → publish flow** — binaries are uploaded to a draft release, notarized manually, then published. Once published, the release is immutable.
+2. **Sigstore transparency log** — the unnotarized binary signature is recorded in the public [Rekor](https://rekor.sigstore.dev/) transparency log.
+3. **SLSA build provenance** — attestation links the artifact to the exact workflow run, commit SHA, and build environment.
+4. **Duplicate tag check** — the release workflow fails if the tag already exists.
 
 ---
 
