ci(release): make the release workflow one-way (publish, never bump) (#170)

simonfaltum · web-flow · commit 20d3b47cc17b · 2026-06-22T09:15:30.000Z
## Why

The release job currently bumps the `version` in
`metaplugin/plugin.meta.json`, pushes that commit to `main`, and then
tags. That makes `main` a write target of the release workflow. We want
publishing to be one-way: the workflow should only read the version
already on `main` and publish it, never write back to the branch.

This is the public-repo half of the one-way publish model. It removes
the reverse write so the only thing that ever writes to `main` is a
merged PR.

## Changes

**Before:** dispatch with a `version` input, run `bump_version.py`,
commit and push the bump to `main`, tag, release.

**Now:** on push to `main` (plus a no-input `workflow_dispatch`
re-trigger), read the version from `metaplugin/plugin.meta.json`, skip
if that tag already exists, otherwise validate, tag, and cut the
release. No bump, no commit, no push to `main`. The only writes are the
tag and the GitHub release, both covered by the DECO-SDK-Tagging App's
existing ruleset bypass (proven by v0.2.6).

How releases are triggered now: a version bump lands on `main` in its
own commit (a normal PR) before this runs. Merging that bump fires the
workflow, the idempotency guard finds no matching tag, and it tags +
releases. Content-only merges find the tag already present and no-op.
Merging this PR itself no-ops, since `main` is already at v0.2.6 and
that tag exists.

`scripts/bump_version.py` is unchanged and still produces the
version-bump commit; it is just no longer invoked by this workflow.

`CONTRIBUTING.md`'s **Releasing** section is rewritten to match: how to
cut a release (bump in a PR, merge it), what does *not* cut a release
(content-only merges and a no-input `workflow_dispatch` both no-op via
the guard), the App/ruleset that lets the tag through, and how to
recover a half-completed release.

Behavioral note: `workflow_dispatch` no longer takes a `version` input.
A manual dispatch re-publishes the version currently on `main` and
no-ops if it is already tagged. It can no longer force-release an
arbitrary version.

## Test plan

- [x] `release.yml` is valid YAML; a structural check confirms the
triggers (`push: main` + no-input dispatch), the idempotency guard, the
guarded validate/tag/release steps, and no remaining `inputs.version` or
push-to-`main`.
- [x] `python3 scripts/skills.py validate` passes on the branch
(unaffected by the workflow change).
- [x] The guard's tag check verified against the live repo: it skips
already-released versions (v0.2.6, v0.2.5, v0.1.0) and matches exactly
(no prefix false-positives, e.g. `v0.2` does not match `v0.2.6`).
- [x] `CONTRIBUTING.md` Releasing section rewritten to the one-way flow.
- [ ] After merge: the `push: main` run reads v0.2.6, finds the tag
exists, and no-ops (no spurious release).
- [ ] Bump the version via a follow-up PR and confirm the merge fires
the workflow, tags, and cuts the release.

This pull request and its description were written by Isaac.

---------

Signed-off-by: simon &lt;simon.faltum@databricks.com&gt;
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,12 +1,14 @@
 name: Release
 
+# Publishes the version already committed in metaplugin/plugin.meta.json: it
+# validates, tags, and cuts the GitHub release, and no-ops if that version is
+# already published. It never bumps the version or pushes to main -- the only
+# writes are the tag and the release. The version is bumped in a separate
+# version-bump commit that lands on main before this runs.
 on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Tag version (e.g. v0.1.0)'
-        required: true
-        type: string
+  push:
+    branches: [main]
+  workflow_dispatch: {}   # manual re-trigger; no inputs
 
 jobs:
   release:
@@ -18,10 +20,10 @@ jobs:
     permissions:
       contents: write
     steps:
-      # Push as the DECO-SDK-Tagging App, not github-actions[bot]. main's
-      # rulesets require PR + merge queue and reject a direct bot push; the App
-      # is on the ruleset bypass list (branch + tag creation), so it can push
-      # the bump commit and the tag directly. Same pattern as databricks-sdk-go.
+      # Push the tag as the DECO-SDK-Tagging App, not github-actions[bot]. main's
+      # rulesets require PR + merge queue and reject a direct bot push; the App is
+      # on the ruleset bypass list (tag creation), so it can push the tag
+      # directly. Same pattern as databricks-sdk-go.
       - name: Generate GitHub App token
         id: generate-token
         uses: actions/create-github-app-token@f8d387b68d61c58ab83c6c016672934102569859 # v3.0.0
@@ -32,102 +34,57 @@ jobs:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           ref: main
-          # Persist the App token so the pushes below carry its credentials.
+          # Persist the App token so the tag push below carries its credentials.
           token: ${{ steps.generate-token.outputs.token }}
 
       - name: Set up Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: '3.11'
 
-      - name: Validate tag format
-        env:
-          VERSION: ${{ inputs.version }}
+      - name: Read version from plugin.meta.json
+        id: version
         run: |
-          if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "Error: version must match vX.Y.Z format"
-            exit 1
+          V="v$(python3 -c 'import json; print(json.load(open("metaplugin/plugin.meta.json"))["version"])')"
+          if [[ ! "$V" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Error: plugin.meta.json version is not vX.Y.Z: $V"; exit 1
           fi
+          echo "version=$V" >> "$GITHUB_OUTPUT"
 
-      - name: Bump version in plugin.meta.json and regenerate manifests
+      - name: Skip if already published
+        id: guard
         env:
-          VERSION: ${{ inputs.version }}
-        run: python3 scripts/bump_version.py "$VERSION"
-
-      - name: Validate generated manifests before publishing
-        # Abort the release if anything is inconsistent (drift, a skill missing
-        # from plugin.meta.json, missing Codex metadata, ...) BEFORE the commit
-        # and tag are pushed, instead of failing the post-push CI after the
-        # release is already published.
-        run: python3 scripts/skills.py validate
-
-      - name: Commit version bump
-        env:
-          VERSION: ${{ inputs.version }}
+          VERSION: ${{ steps.version.outputs.version }}
         run: |
-          # Commit as the App. The email must be the App's noreply address or
-          # the commit will not be verified.
-          git config user.name "Databricks SDK Release Bot"
-          git config user.email "DECO-SDK-Tagging[bot]@users.noreply.github.com"
-          # metaplugin/plugin.meta.json is the source; bump_version.py regenerates
-          # the full set from it: the four marketplace.json catalogs (Cursor's is
-          # new), the routing files, the four hook-wiring dialects, manifest.json,
-          # and the whole plugins/databricks/ bundle (copies + the four plugin.json
-          # with the bumped version). Stage every one (unchanged files are a no-op)
-          # so a release can never commit a partial set. The four plugin.json now
-          # live INSIDE the bundle, so the `plugins/databricks` directory covers
-          # them. (The catalogs currently pin `ref: main`; once the tag-pinning
-          # follow-up lands they re-stamp to the new tag here too.)
-          git add \
-            metaplugin/plugin.meta.json \
-            .claude-plugin/marketplace.json \
-            .github/plugin/marketplace.json \
-            .agents/plugins/marketplace.json \
-            .cursor-plugin/marketplace.json \
-            hooks/_routing_data.json \
-            rules/databricks-routing.mdc \
-            rules/README.md \
-            hooks/hooks.json \
-            hooks/codex-hooks.json \
-            hooks/copilot-hooks.json \
-            hooks/cursor-hooks.json \
-            manifest.json \
-            plugins/databricks
-          # Guard the "stage the full set" invariant: if bump_version.py ever
-          # regenerates a tracked file not staged above (a new generated artifact
-          # added without updating this list), fail loudly instead of publishing
-          # the tag and leaving the regenerated file uncommitted -- which
-          # post-merge CI on main would then flag as drift.
-          if ! git diff --quiet; then
-            echo "Error: bump_version.py changed tracked files not staged for the release commit:"
-            git diff --name-only
-            exit 1
-          fi
-          if git diff --cached --quiet; then
-            echo "Manifests already at $VERSION; nothing to commit"
+          # Query the remote tags directly; no local tag fetch needed.
+          if git ls-remote --exit-code --tags origin "refs/tags/$VERSION" >/dev/null 2>&1; then
+            echo "already=true" >> "$GITHUB_OUTPUT"
+            echo "$VERSION is already published; nothing to do."
           else
-            git commit -s -m "chore(release): bump plugin manifests to $VERSION"
-            git push origin HEAD:main
+            echo "already=false" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Validate manifests before publishing
+        if: steps.guard.outputs.already == 'false'
+        # Safety gate: the tree on main is already generated and consistent, so
+        # this is a no-op pass. It aborts the release if drift somehow reached
+        # main, before a tag is cut.
+        run: python3 scripts/skills.py validate
+
       - name: Create annotated tag
+        if: steps.guard.outputs.already == 'false'
         env:
-          VERSION: ${{ inputs.version }}
+          VERSION: ${{ steps.version.outputs.version }}
         run: |
-          # git identity is already configured by the "Commit version bump"
-          # step above and persists for the job via .git/config.
-          # Annotated tag (objecttype=tag), not lightweight (objecttype=commit):
-          # records tagger metadata and is the prerequisite for `git tag -v`
-          # verification if tag signing is ever enabled.
+          # Email must be the App's noreply address or the tag/commit is unverified.
+          git config user.name "Databricks SDK Release Bot"
+          git config user.email "DECO-SDK-Tagging[bot]@users.noreply.github.com"
           git tag -a "$VERSION" -m "$VERSION"
           git push origin "$VERSION"
 
       - name: Create release
+        if: steps.guard.outputs.already == 'false'
         env:
           GH_TOKEN: ${{ steps.generate-token.outputs.token }}
-          VERSION: ${{ inputs.version }}
-        run: |
-          gh release create "$VERSION" \
-            --title "$VERSION" \
-            --generate-notes \
-            --verify-tag
+          VERSION: ${{ steps.version.outputs.version }}
+        run: gh release create "$VERSION" --title "$VERSION" --generate-notes --verify-tag
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -156,36 +156,59 @@ Examples in skills and references must follow secure defaults:
 
 ## Releasing
 
-Releases are cut by the **Release** workflow (`.github/workflows/release.yml`),
-triggered manually (`workflow_dispatch`) with a `vX.Y.Z` tag. The workflow:
-
-1. Runs `scripts/bump_version.py <version>`, which sets the `version` field in
-   `plugin.meta.json` (the single source) and regenerates every target's
-   `plugin.json` + each `marketplace.json` catalog, `manifest.json`, and the
-   `plugins/databricks/` bundle from it, so all four targets carry the same
-   version.
-2. Commits the bump (`plugin.meta.json` + the regenerated catalogs, manifest, and
-   the `plugins/databricks/` bundle) to `main`.
-3. Creates an annotated `vX.Y.Z` tag (`git tag -a`) at that commit, pushes it,
-   then creates the GitHub release (`gh release create --verify-tag`).
-
-The catalogs currently track `main` (`ref: main`), so the bundle the catalogs
-serve is whatever is committed on `main` — releases bump the version but do not
-change which ref installs follow. A planned follow-up flips
-`marketplace.source.ref_template` to `v{version}`; once it lands, each release
-re-stamps the ref-capable catalogs to the new tag, and the release tag must
-contain the `plugins/databricks/` bundle (it does, since the bundle is committed
-on `main`). Cut that bump-and-tag in one motion so a catalog never names a tag
-that does not exist yet.
-
-Bumping the plugin `version` on every release is **required**: Claude Code's
-plugin marketplace keys updates on the `version` field, so a release that ships
-without bumping it leaves marketplace clients on the cached copy and they never
-see the new skills.
-
-After releasing, open a follow-up PR to update
-[`cli-compat.json`](#version-resolution-in-databricks-cli) in the CLI repo so
-`databricks aitools install` resolves to the new version.
+Publishing is **one-way**: the **Release** workflow
+(`.github/workflows/release.yml`) only *reads* the version already committed on
+`main` and publishes it. It never bumps the version or pushes a commit to
+`main`; the only writes it makes are the release tag and the GitHub release.
+
+### Cutting a release
+
+1. **Bump the version in its own PR.** Run `python3 scripts/bump_version.py
+   vX.Y.Z`, which sets the `version` field in `metaplugin/plugin.meta.json` (the
+   single source) and regenerates every target from it (each `plugin.json`, the
+   four `marketplace.json` catalogs, `manifest.json`, and the
+   `plugins/databricks/` bundle), so all four targets carry the same version.
+   Commit the regenerated tree and open a PR.
+2. **Merge the bump PR.** The push to `main` triggers the Release workflow. It
+   reads the new version from `plugin.meta.json`, confirms no `vX.Y.Z` tag exists
+   yet, runs `scripts/skills.py validate` as a safety gate, creates the annotated
+   `vX.Y.Z` tag, pushes it, and creates the GitHub release (`gh release create
+   --verify-tag`).
+
+That is the whole release: no manual version argument, no separate publish step.
+
+### What does not cut a release
+
+- **Content-only merges** (anything that leaves the `version` field unchanged):
+  the workflow still runs on the push to `main`, but the tag for the current
+  version already exists, so the idempotency guard short-circuits and it no-ops.
+- **A manual `workflow_dispatch`** (it takes no inputs): this re-runs the publish
+  for whatever version is on `main` and no-ops if that version is already tagged.
+  It cannot force-release an arbitrary version.
+
+The tag is pushed by the DECO-SDK-Tagging GitHub App, which is on the branch and
+tag-creation ruleset bypass lists; `main` otherwise requires every change to go
+through a PR and the merge queue.
+
+### Notes
+
+- **Bumping the `version` is required** for every release. Claude Code's plugin
+  marketplace keys updates on the `version` field, so a release that ships
+  without bumping it leaves marketplace clients on the cached copy and they never
+  see the new skills.
+- The catalogs currently track `main` (`ref: main`), so the bundle they serve is
+  whatever is committed on `main`; bumping the version does not change which ref
+  installs follow. A planned follow-up flips `marketplace.source.ref_template` to
+  `v{version}` so the ref-capable catalogs re-stamp to each release tag (the tag
+  contains the `plugins/databricks/` bundle, since it is committed on `main`).
+- **If a release half-completes** (the tag was pushed but the GitHub release was
+  not created, for example the job died between the two steps), the guard treats
+  the version as already published and skips it on the next run. Recover by
+  creating the release manually (`gh release create vX.Y.Z --verify-tag
+  --generate-notes`) or by deleting the tag and re-running the workflow.
+- After releasing, open a follow-up PR to update
+  [`cli-compat.json`](#version-resolution-in-databricks-cli) in the CLI repo so
+  `databricks aitools install` resolves to the new version.
 
 ## Version resolution in Databricks CLI
 
