diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0966a26..6b13c54 100644 --- a/.github/workflows/release.yml +++ b/.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 ` 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 diff --git a/README.md b/README.md index d0d5caa..23d5549 100644 --- a/README.md +++ b/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 `. +Release tags are annotated (`git tag -a`) so `git tag -v ` 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 diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..8ba5ec7 --- /dev/null +++ b/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.