release: switch workflow to annotated tags + add RELEASING.md

.github/workflows/release.yml

@@ -27,11 +27,24 @@ jobs:
             exit 1
           fi
 
-      - name: Create tag and release
+      - name: Create annotated tag
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$VERSION" -m "$VERSION"
+          # Tag is annotated (objecttype=tag) so `git tag -v <tag>` can verify
+          # signatures once GPG/Sigstore signing lands. Today the tag is
+          # annotated but unsigned — see RELEASING.md.
+          git push origin "$VERSION"
+
+      - name: Create release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VERSION: ${{ inputs.version }}
         run: |
           gh release create "$VERSION" \
             --title "$VERSION" \
-            --generate-notes
+            --generate-notes \
+            --verify-tag

README.md

@@ -149,7 +149,7 @@ Please see [SECURITY](./SECURITY) for vulnerability reporting guidelines.
 
 ## Integrity
 
-All future release tags will be GPG-signed and verifiable via `git tag -v <tag>`.
+Release tags are annotated (`git tag -a`) so `git tag -v <tag>` can verify them once GPG or Sigstore signing is enabled in the release workflow. See [RELEASING.md](./RELEASING.md) for verification steps and the current signing status.
 
 ## Contributing
 

RELEASING.md

@@ -0,0 +1,41 @@
+# Releasing
+
+This repo is released via tagged GitHub releases. Releases are cut from `main`.
+
+## How to cut a release
+
+Run the `Release` workflow from the [Actions tab](https://github.com/databricks/databricks-agent-skills/actions/workflows/release.yml) and supply the version (e.g. `v0.3.0`).
+
+The workflow:
+
+1. Validates the version matches `vX.Y.Z`.
+2. Creates an **annotated** git tag (`git tag -a`).
+3. Pushes the tag to origin.
+4. Creates a GitHub Release with auto-generated notes (`--verify-tag` confirms the tag exists).
+
+## Verifying a release tag
+
+```bash
+git fetch --tags
+git tag -v v0.3.0
+```
+
+`git tag -v` only works on annotated tags — lightweight tags have no metadata to verify.
+
+## Signing — status
+
+The annotated-tag step above is a prerequisite for signing; without it, there is nothing to sign. Signing itself is **not yet enabled**: today the workflow creates annotated tags without a GPG/Sigstore signature.
+
+Path forward:
+
+- **GPG**: provision a release-identity GPG key, store the private key + passphrase in GH Actions secrets, and add a sign step that runs `git tag -s` instead of `git tag -a`. Verification stays `git tag -v`.
+- **Sigstore (gitsign)**: install [`sigstore/gitsign`](https://github.com/sigstore/gitsign) in the workflow and set `gpg.format=x509`. No long-lived secret; the runner's OIDC token is the identity. Verification stays `git tag -v` plus `gitsign verify`.
+
+Either approach satisfies the `README.md` "Integrity" claim that future tags are signed and verifiable. The README claim was added when the repo was still using lightweight tags — switching to annotated tags here unblocks it.
+
+## Existing tags
+
+`v0.1.0` through `v0.2.1` are **lightweight** tags (`git for-each-ref --format='%(objecttype)' refs/tags` returns `commit`, not `tag`). They cannot be retroactively GPG-signed without re-tagging. If the project wants verifiable history, two options:
+
+- Delete and re-create as annotated signed tags (rewrites the public tag history — coordinate with downstream consumers).
+- Leave them as-is and start signing from the next release.