ci(docs): enforce signed release tags and verification (#175)

## Summary
Implements OpenSSF `version_tags_signed` for release tags.

- Document release tag signing policy and verification in
`CONTRIBUTING.md`
- Add end-user tag verification guidance to `README.md`
- Update release workflow to create signed tags using Sigstore `gitsign`
- Add tag signature verification workflow for pushed `v*` tags

## Validation
- `get_errors` reports no editor diagnostics in updated files
- Local markdown/yaml npm lint commands were not runnable in this
environment because required CLIs (`markdownlint-cli2`, `pwsh`) are not
installed
- Tested using workflow in my fork, unsigned fails and signed succeeds 

https://github.com/akhanattentive/physical-ai-toolchain/actions
## OpenSSF
- Addresses requirement: `version_tags_signed`

## Notes
- Uses keyless Sigstore signing (`gitsign`) instead of distributed
maintainer GPG keys

---------

Co-authored-by: Ali Khan <khana@microsoft.com>
Co-authored-by: Marcel Bindseil <marcelbindseil@gmail.com>
Co-authored-by: Bill Berry <WilliamBerryiii@users.noreply.github.com>

Author: 4 people

.cspell/general-technical.txt

@@ -1553,14 +1553,17 @@ auditable
 auditability
 auditifnotexists
 gdpr
+gitsign
 hipaa
+keyless
 oidc
 OSSF
 passwordless
 siem
 sox
 Sarbanes
 Oxley
+x509
 
 # Cloud Platforms & Services (not covered by public dicts)
 amazonaws

.github/workflows/main.yml

@@ -145,6 +145,7 @@ jobs:
       cancel-in-progress: false
     permissions:
       contents: read
+      id-token: write
     outputs:
       release_created: ${{ steps.release.outputs.release_created }}
       tag_name: ${{ steps.release.outputs.tag_name }}
@@ -202,33 +203,91 @@ jobs:
           git commit -m "chore: regenerate uv.lock"
           git push
 
+      - name: Checkout default branch for tag signing
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v4.2.2
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          fetch-depth: 0
+
+      - name: Install gitsign
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        run: |
+          $version = 'v0.13.0'
+          $arch = '${{ runner.arch }}'
+
+          switch ($arch) {
+            'X64' {
+              $asset = 'gitsign_0.13.0_linux_amd64'
+              $expectedSha = '011af11d57ad205b4ae4e3f41ecc8c64fbe0043c829190c0cb44fce6fce74bbb'
+            }
+            'ARM64' {
+              $asset = 'gitsign_0.13.0_linux_arm64'
+              $expectedSha = 'f0ec4732696b88f133ab6ef9ac2fe8be843ab9540bd1cc51dc4143142a858372'
+            }
+            default {
+              throw "Unsupported runner architecture: $arch"
+            }
+          }
+
+          $assetUrl = "https://github.com/sigstore/gitsign/releases/download/$version/$asset"
+          $assetPath = Join-Path $env:RUNNER_TEMP $asset
+          Invoke-WebRequest -Uri $assetUrl -OutFile $assetPath
+
+          $actualSha = (Get-FileHash -Path $assetPath -Algorithm SHA256).Hash.ToLowerInvariant()
+          if ($actualSha -ne $expectedSha) {
+            throw "Checksum verification failed for $asset. Expected $expectedSha but got $actualSha"
+          }
+
+          $binDir = Join-Path $env:RUNNER_TEMP 'bin'
+          New-Item -ItemType Directory -Force -Path $binDir | Out-Null
+          $gitsign = Join-Path $binDir 'gitsign'
+          Move-Item -Path $assetPath -Destination $gitsign -Force
+          chmod +x $gitsign
+          Add-Content -Path $env:GITHUB_PATH -Value $binDir
+          & $gitsign version
+
       # Workaround: release-please with "draft": true uses lazy tag
       # creation. The git tag is not materialized until the release is
       # published. Without the tag, release-please cannot find the draft
       # on subsequent runs, breaking version anchoring and causing bogus
       # changelog entries. The skip-github-pull-request conditional above
       # prevents PR creation on release commits (zero unreleased changes),
-      # and this step creates the tag so subsequent runs find the release.
+      # and this step creates a signed tag so subsequent runs find the release.
       # Replace both workarounds with "force-tag-creation": true in
       # release-please-config.json once release-please-action ships a
       # version that includes googleapis/release-please#2627.
-      - name: Create git tag for draft release
+      - name: Create signed git tag for draft release
         if: ${{ steps.release.outputs.release_created == 'true' }}
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
         run: |
+          git config --global gpg.format x509
+          git config --global gpg.x509.program gitsign
+          git config --global tag.gpgSign true
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git fetch --tags --force
+
           $tag = '${{ steps.release.outputs.tag_name }}'
-          $repo = '${{ github.repository }}'
-          $null = gh api "/repos/$repo/git/refs/tags/$tag" --silent 2>&1
-          if ($LASTEXITCODE -ne 0) {
-            gh api "/repos/$repo/git/refs" `
-              -f "ref=refs/tags/$tag" `
-              -f "sha=${{ github.sha }}"
-            Write-Output "Created git tag $tag -> ${{ github.sha }}"
-          } else {
+          $existingTag = git tag --list $tag
+          if ($existingTag) {
             Write-Output "Git tag $tag already exists"
+            exit 0
           }
 
+          git remote set-url origin "https://x-access-token:${env:GH_TOKEN}@github.com/${env:GITHUB_REPOSITORY}.git"
+          git tag -s $tag $env:GITHUB_SHA -m "Release $tag"
+          git push origin "refs/tags/$tag"
+          Write-Output "Created signed git tag $tag -> $env:GITHUB_SHA"
+
+      - name: Verify signed git tag
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        run: |
+          $tag = '${{ steps.release.outputs.tag_name }}'
+          git tag -v $tag
+
   # Sign release artifacts and generate SBOM attestation
   attest-release:
     if: ${{ needs.release-please.outputs.release_created == 'true' }}

.github/workflows/verify-tag-signature.yml

@@ -0,0 +1,69 @@
+name: Verify Release Tag Signature
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify-release-tag:
+    name: Verify pushed release tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Install gitsign
+        run: |
+          VERSION="v0.13.0"
+
+          case "${{ runner.arch }}" in
+            X64)
+              ASSET="gitsign_0.13.0_linux_amd64"
+              EXPECTED_SHA="011af11d57ad205b4ae4e3f41ecc8c64fbe0043c829190c0cb44fce6fce74bbb"
+              ;;
+            ARM64)
+              ASSET="gitsign_0.13.0_linux_arm64"
+              EXPECTED_SHA="f0ec4732696b88f133ab6ef9ac2fe8be843ab9540bd1cc51dc4143142a858372"
+              ;;
+            *)
+              echo "Unsupported runner architecture: ${{ runner.arch }}"
+              exit 1
+              ;;
+          esac
+
+          BASE_URL="https://github.com/sigstore/gitsign/releases/download/${VERSION}"
+          curl -fsSLo "${RUNNER_TEMP}/${ASSET}" "${BASE_URL}/${ASSET}"
+
+          echo "${EXPECTED_SHA}  ${RUNNER_TEMP}/${ASSET}" | sha256sum -c -
+
+          BIN_DIR="${RUNNER_TEMP}/bin"
+          mkdir -p "${BIN_DIR}"
+          install -m 0755 "${RUNNER_TEMP}/${ASSET}" "${BIN_DIR}/gitsign"
+          echo "${BIN_DIR}" >> "${GITHUB_PATH}"
+
+      - name: Configure git x509 verifier
+        run: |
+          git config --global gpg.format x509
+          git config --global gpg.x509.program gitsign
+
+      - name: Verify tag signature
+        env:
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          tag_type="$(git cat-file -t "refs/tags/${TAG_NAME}")"
+          if [ "${tag_type}" != "tag" ]; then
+            echo "Expected annotated tag object for ${TAG_NAME}, found ${tag_type}"
+            exit 1
+          fi
+
+          git tag -v "${TAG_NAME}"

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 title: Contributing
 description: How to contribute to the Physical AI Toolchain
 author: Microsoft Robotics-AI Team
-ms.date: 2026-02-11
+ms.date: 2026-03-11
 ms.topic: how-to
 keywords:
   - contributing
@@ -212,6 +212,43 @@ After merging to `main`, release-please automatically creates a release PR with
 
 For commit message format details, see [commit-message.instructions.md](.github/instructions/commit-message.instructions.md).
 
+## Release Tag Signing
+
+All release tags are required to be signed. Unsigned release tags are non-compliant with project policy.
+
+This repository uses Sigstore `gitsign` with GitHub OIDC identity for keyless tag signing.
+
+### Configure Signing
+
+```bash
+# Install gitsign
+# https://docs.sigstore.dev/cosign/signing/gitsign/
+
+# Configure git for keyless x509 signing
+git config --global gpg.format x509
+git config --global gpg.x509.program gitsign
+git config --global tag.gpgSign true
+```
+
+### Create a Signed Release Tag
+
+```bash
+git tag -s v1.0.0 -m "Release v1.0.0"
+git push origin v1.0.0
+```
+
+### Verify a Signed Tag
+
+```bash
+git fetch --tags
+git tag -v v1.0.0
+```
+
+GitHub Actions validates signatures for pushed version tags (`v*`).
+
+> [!IMPORTANT]
+> Maintainer GPG key distribution is not required for this repository because release tags are signed using keyless Sigstore identities.
+
 ## Deprecation Policy
 
 External interfaces follow a formal deprecation lifecycle before removal. The policy covers shell script arguments, environment variables, Terraform variables and outputs, configuration schemas, and workflow templates.

README.md

@@ -65,6 +65,17 @@ Contributions are welcome. Whether fixing documentation or adding new training t
 2. Review [open issues](https://github.com/microsoft/physical-ai-toolchain/issues)
 3. See the [prerequisites](docs/contributing/prerequisites.md) for required tools
 
+## Verifying Git Tags
+
+All release tags are signed. Verify a release tag before using it in production workflows:
+
+```bash
+git fetch --tags
+git tag -v v1.0.0
+```
+
+This repository uses Sigstore `gitsign` keyless signing for release tags. For tag signing policy and maintainer guidance, see [CONTRIBUTING.md](CONTRIBUTING.md#release-tag-signing).
+
 ## Roadmap
 
 See the [project roadmap](docs/contributing/ROADMAP.md) for priorities, timelines, and success metrics.