ci: gate VS Code tags on exact-SHA release preflight

Author: zackees

.github/workflows/vscode-extension-release.yml

@@ -1,55 +1,156 @@
 name: Release VS Code extension
 
 on:
-  push:
-    tags: ["vscode-v*"]
+  workflow_dispatch:
+    inputs:
+      candidate_sha:
+        description: Exact 40-character branch-head commit SHA to release
+        required: true
+        type: string
+      dry_run:
+        description: Validate full CI and VSIX artifacts without tagging or publishing
+        required: false
+        default: false
+        type: boolean
 
-# Never cancelled and never coalesced: every publish runs to completion.
 concurrency:
   group: ${{ github.workflow }}-${{ github.run_id }}
   cancel-in-progress: false
 
+permissions:
+  contents: read
+  actions: read
+
 jobs:
   full-coverage:
     runs-on: ubuntu-24.04
-    permissions:
-      actions: read
-      contents: read
     steps:
       - uses: actions/checkout@v4
-      - name: Require exact-SHA full release CI before publication
+        with:
+          ref: ${{ inputs.candidate_sha }}
+      - name: Require exact-SHA full release CI before tagging
         env:
           GH_TOKEN: ${{ github.token }}
-        run: python ci/verify_full_coverage.py --sha "$GITHUB_SHA"
+          EXPECTED_SHA: ${{ inputs.candidate_sha }}
+        run: |
+          [[ "$EXPECTED_SHA" =~ ^[0-9a-f]{40}$ ]]
+          [[ "$GITHUB_REF" == refs/heads/* ]]
+          test "$EXPECTED_SHA" = "$GITHUB_SHA"
+          test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
+          python ci/verify_full_coverage.py --sha "$EXPECTED_SHA"
 
-  validate-tag:
+  validate-version:
+    needs: [full-coverage]
     runs-on: ubuntu-24.04
     outputs:
       version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.version.outputs.tag }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.candidate_sha }}
       - id: version
+        env:
+          EXPECTED_SHA: ${{ inputs.candidate_sha }}
         run: |
+          test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
           VERSION=$(node -p "require('./vscode-plugin/package.json').version")
-          test "${GITHUB_REF_NAME}" = "vscode-v${VERSION}"
+          TAG="vscode-v${VERSION}"
+          if git ls-remote --exit-code --tags origin "refs/tags/${TAG}" >/dev/null 2>&1; then
+            git fetch --no-tags origin "refs/tags/${TAG}:refs/tags/${TAG}"
+            test "$(git rev-parse "${TAG}^{commit}")" = "$EXPECTED_SHA" || {
+              echo "Existing tag ${TAG} points to another commit" >&2
+              exit 1
+            }
+          fi
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+
   build:
-    needs: [validate-tag, full-coverage]
-    if: needs.full-coverage.result == 'success'
+    needs: [full-coverage, validate-version]
+    if: needs.full-coverage.result == 'success' && needs.validate-version.result == 'success'
     uses: ./.github/workflows/vscode-extension.yml
     with:
       release_build: true
+
+  artifact-preflight:
+    needs: [full-coverage, validate-version, build]
+    if: needs.full-coverage.result == 'success' && needs.validate-version.result == 'success' && needs.build.result == 'success'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.candidate_sha }}
+      - uses: actions/download-artifact@v4
+        with: { pattern: vscode-*, path: artifacts, merge-multiple: true }
+      - name: Validate the seven VSIX packages before tagging
+        env:
+          VERSION: ${{ needs.validate-version.outputs.version }}
+          EXPECTED_SHA: ${{ inputs.candidate_sha }}
+        run: |
+          test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
+          python ci/vscode_release_artifact_lint.py --artifacts artifacts --version "$VERSION"
+
+  create-tag:
+    needs: [full-coverage, validate-version, artifact-preflight]
+    if: >-
+      !cancelled() &&
+      inputs.dry_run != true &&
+      needs.full-coverage.result == 'success' &&
+      needs.validate-version.result == 'success' &&
+      needs.artifact-preflight.result == 'success'
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.candidate_sha }}
+      - name: Create release tag from the verified commit
+        env:
+          EXPECTED_SHA: ${{ inputs.candidate_sha }}
+          TAG: ${{ needs.validate-version.outputs.tag }}
+        run: |
+          test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          if git ls-remote --exit-code --tags origin "refs/tags/${TAG}" >/dev/null 2>&1; then
+            git fetch --no-tags origin "refs/tags/${TAG}:refs/tags/${TAG}"
+            test "$(git rev-parse "${TAG}^{commit}")" = "$EXPECTED_SHA" || {
+              echo "Existing tag ${TAG} points to another commit" >&2
+              exit 1
+            }
+          else
+            git tag -a "$TAG" -m "Release VS Code ${{ needs.validate-version.outputs.version }}"
+            git push origin "refs/tags/${TAG}"
+          fi
+
   publish:
-    needs: [validate-tag, full-coverage, build]
-    if: needs.full-coverage.result == 'success' && needs.build.result == 'success'
+    needs: [full-coverage, validate-version, artifact-preflight, create-tag]
+    if: >-
+      !cancelled() &&
+      inputs.dry_run != true &&
+      needs.full-coverage.result == 'success' &&
+      needs.artifact-preflight.result == 'success' &&
+      needs.create-tag.result == 'success'
     runs-on: ubuntu-24.04
     permissions:
       contents: write
       id-token: write
       attestations: write
     steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.candidate_sha }}
       - uses: actions/download-artifact@v4
-        with: { path: artifacts, merge-multiple: true }
+        with: { pattern: vscode-*, path: artifacts, merge-multiple: true }
+      - name: Verify release artifacts again
+        env:
+          VERSION: ${{ needs.validate-version.outputs.version }}
+          EXPECTED_SHA: ${{ inputs.candidate_sha }}
+        run: |
+          test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
+          python ci/vscode_release_artifact_lint.py --artifacts artifacts --version "$VERSION"
       - name: Produce checksums
         run: |
           cd artifacts
@@ -60,7 +161,9 @@ jobs:
       - name: Create GitHub release from the verified package bytes
         env:
           GH_TOKEN: ${{ github.token }}
-        run: gh release create "$GITHUB_REF_NAME" artifacts/* --title "FastLED VS Code ${{ needs.validate-tag.outputs.version }}" --generate-notes
+          TAG: ${{ needs.validate-version.outputs.tag }}
+          VERSION: ${{ needs.validate-version.outputs.version }}
+        run: gh release create "$TAG" artifacts/* --title "FastLED VS Code $VERSION" --generate-notes
       - name: Publish those same prebuilt VSIX files to Marketplace
         env:
           VSCE_PAT: ${{ secrets.VSCE_PAT }}

.github/workflows/vscode-extension.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
     inputs:
       release_build:
-        description: Build VSIX artifacts for the tag-triggered release caller
+        description: Build VSIX artifacts for the exact-SHA release caller
         required: false
         type: boolean
         default: false

CLAUDE.md

@@ -21,7 +21,9 @@ If `soldr` is not on PATH, install it with `uv tool install soldr`.
 Ordinary PR/main CI is minimal. The literal `ci-test` PR label adds Linux x86
 unit and integration tests; `ci-full` runs the platform matrix. Full validation
 must pass on the exact release SHA before tagging or publishing. A version bump
-on `main` no longer starts a release. See [fractional CI and release gates](docs/FRACTIONAL_CI.md).
+on `main` or a pushed VS Code tag no longer starts a release. Both CLI and
+VS Code releases require manual exact-SHA dispatch and artifact preflight.
+See [fractional CI and release gates](docs/FRACTIONAL_CI.md).
 
 `bash test` runs the Python API smoke tests plus the Rust workspace tests. End-to-end WASM compiles should be run only when the change touches the native build backend.
 

ci/vscode_release_artifact_lint.py

@@ -0,0 +1,54 @@
+"""Validate the complete VS Code release payload before creating its tag."""
+
+import argparse
+import json
+import zipfile
+from pathlib import Path
+
+TARGETS = frozenset(
+    {
+        "win32-x64",
+        "win32-arm64",
+        "linux-x64",
+        "linux-arm64",
+        "darwin-x64",
+        "darwin-arm64",
+        "universal",
+    }
+)
+
+
+def check(artifacts: Path, version: str) -> list[Path]:
+    expected = {f"fastled-wasm-{version}-{target}.vsix" for target in TARGETS}
+    found = {path.name for path in artifacts.iterdir() if path.is_file()}
+    if found != expected:
+        raise ValueError(
+            f"expected exact seven versioned VSIX files: {sorted(expected)}; got {sorted(found)}"
+        )
+    packages = sorted(artifacts / name for name in expected)
+    for package in packages:
+        if package.stat().st_size == 0:
+            raise ValueError(f"empty VSIX: {package.name}")
+        try:
+            with zipfile.ZipFile(package) as archive:
+                if archive.testzip() is not None:
+                    raise ValueError(f"corrupt VSIX: {package.name}")
+                manifest = json.loads(archive.read("extension/package.json"))
+        except (zipfile.BadZipFile, KeyError, json.JSONDecodeError) as error:
+            raise ValueError(f"invalid VSIX: {package.name}: {error}") from error
+        if manifest.get("name") != "fastled-wasm" or manifest.get("version") != version:
+            raise ValueError(f"VSIX manifest mismatch: {package.name}")
+    return packages
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--artifacts", type=Path, required=True)
+    parser.add_argument("--version", required=True)
+    args = parser.parse_args()
+    packages = check(args.artifacts, args.version)
+    print(f"Validated {len(packages)} VSIX packages for version {args.version}")
+
+
+if __name__ == "__main__":
+    main()

docs/FRACTIONAL_CI.md

@@ -29,8 +29,13 @@ candidate_sha=<40-hex-sha> -f dry_run=true`. The branch tip must be that SHA.
 The preflight rejects missing/corrupt wheels, missing binaries, and wheels at
 or above 100 MB; it cannot reserve a PyPI upload or verify the project's
 remaining storage quota. A conflicting tag is rejected before the six builds.
-The VS Code tag-push publication workflow checks the same report before
-building or publishing.
+The VS Code extension release is also manual-only. Dispatch
+`vscode-extension-release.yml` at the candidate branch with the same
+`candidate_sha`; `dry_run=true` exercises its seven-platform VSIX build and
+artifact preflight without creating `vscode-v<version>` or publishing. A real
+attempt checks the exact-SHA full-coverage report, builds and validates all
+seven version-matched VSIX files, and only then creates the VS Code tag and
+publishes. Pushing a `vscode-v*` tag does not start a release workflow.
 
 The normalized issue-driven release front door and automated dispatch of the
 29 full workflows are still pending. A candidate must currently be the tip of

tests/unit/test_ci_modes.py

@@ -66,6 +66,53 @@ def test_vscode_matrix_only_runs_for_full_pr_or_tag_release():
     assert "release_build: true" in release
 
 
+def test_vscode_release_cannot_create_tag_before_full_coverage_and_preflight():
+    release = (WORKFLOWS / "vscode-extension-release.yml").read_text()
+    assert "  push:\n    tags:" not in release
+    assert "  workflow_dispatch:" in release
+    assert "candidate_sha:" in release
+    assert "dry_run:" in release
+    assert "verify_full_coverage.py" in release
+    assert "vscode_release_artifact_lint.py" in release
+    assert "  create-tag:" in release
+    tag = release.split("  create-tag:\n", 1)[1].split("  publish:\n", 1)[0]
+    assert "needs.full-coverage.result == 'success'" in tag
+    assert "needs.artifact-preflight.result == 'success'" in tag
+    assert "inputs.dry_run != true" in tag
+    assert 'test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"' in tag
+    assert "git push origin" in tag
+    publish = release.split("  publish:\n", 1)[1]
+    assert "needs.create-tag.result == 'success'" in publish
+
+
+def test_vscode_release_artifact_lint_rejects_missing_corrupt_and_wrong_version(
+    tmp_path,
+):
+    spec = importlib.util.spec_from_file_location(
+        "vscode_release_artifact_lint", ROOT / "ci" / "vscode_release_artifact_lint.py"
+    )
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    targets = {
+        "win32-x64", "win32-arm64", "linux-x64", "linux-arm64",
+        "darwin-x64", "darwin-arm64", "universal",
+    }
+    for target in targets:
+        with zipfile.ZipFile(
+            tmp_path / f"fastled-wasm-1.0.1-{target}.vsix", "w"
+        ) as archive:
+            archive.writestr(
+                "extension/package.json", json.dumps({"name": "fastled-wasm", "version": "1.0.1"})
+            )
+    assert len(module.check(tmp_path, "1.0.1")) == 7
+    with pytest.raises(ValueError):
+        module.check(tmp_path, "1.0.2")
+    (tmp_path / "fastled-wasm-1.0.1-universal.vsix").write_bytes(b"corrupt")
+    with pytest.raises(ValueError):
+        module.check(tmp_path, "1.0.1")
+
+
 def test_release_does_not_wait_for_removed_routine_build_artifacts():
     workflow = (WORKFLOWS / "auto-release.yml").read_text()
     assert "collect-artifacts:" not in workflow