SocketDev · lelia · Aug 12, 2026 · Aug 12, 2026
@@ -19,11 +19,10 @@
 
 ### Release checklist (skip for non-release PRs)
 
-<!-- Only fill this out if this PR is cutting a new release (e.g. v2.1.0). -->
-
-- [ ] `pyproject.toml` `version:` field updated to new version
-- [ ] `python3 scripts/sync_release_version.py --write` run after updating `pyproject.toml`
-- [ ] `socket_basics/version.py` updated to new version
-- [ ] `socket_basics/__init__.py` updated to the same version
-- [ ] `action.yml` `image:` ref updated to `docker://ghcr.io/socketdev/socket-basics:<new-version>`
-- [ ] `CHANGELOG.md` updated with human-authored release notes for this version
+<!-- Only fill this out if this PR is cutting a new release (e.g. v3.1.0). -->
+
+- [ ] `python3 scripts/prep_release.py --version <new-version>` completed successfully
+- [ ] Release metadata and `uv.lock` are synchronized
+- [ ] Current-release references in README and docs are synchronized
+- [ ] `CHANGELOG.md` contains reviewed, human-authored notes for this version
+- [ ] Release PR will be merged before its merge commit is tagged
@@ -9,6 +9,11 @@ on:
       - "pyproject.toml"
       - "uv.lock"
       - "action.yml"
+      - "README.md"
+      - "docs/**/*.md"
+      - "scripts/check_release_docs.py"
+      - "scripts/prep_release.py"
+      - "scripts/sync_release_version.py"
       - ".github/workflows/python-tests.yml"
   pull_request:
     paths:
@@ -17,6 +22,11 @@ on:
       - "pyproject.toml"
       - "uv.lock"
       - "action.yml"
+      - "README.md"
+      - "docs/**/*.md"
+      - "scripts/check_release_docs.py"
+      - "scripts/prep_release.py"
+      - "scripts/sync_release_version.py"
       - ".github/workflows/python-tests.yml"
   workflow_dispatch:
 
@@ -53,5 +63,7 @@ jobs:
         run: uv lock --locked
       - name: 🔒 Assert release version metadata is in sync
         run: python3 scripts/sync_release_version.py --check
+      - name: 📚 Assert current-release docs are in sync
+        run: python3 scripts/check_release_docs.py --check
       - name: 🧪 Run tests
         run: uv run --no-sync pytest -q tests/
@@ -35,7 +35,7 @@ jobs:
       - name: Run Socket Basics
         # Pin to a commit SHA for supply-chain safety.
         # Dependabot will keep this up to date automatically — see docs/github-action.md.
-        uses: SocketDev/socket-basics@<sha>  # v2.0.3
+        uses: SocketDev/socket-basics@<sha>  # v3.0.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -178,10 +178,10 @@ For GitHub Actions, see the [Quick Start](#-quick-start---github-actions) above
 
 ```bash
 # Pull the pre-built image (recommended — no build step required)
-docker pull ghcr.io/socketdev/socket-basics:2.0.3
+docker pull ghcr.io/socketdev/socket-basics:3.0.0
 
 # Run scan
-docker run --rm -v "$PWD:/workspace" ghcr.io/socketdev/socket-basics:2.0.3 \
+docker run --rm -v "$PWD:/workspace" ghcr.io/socketdev/socket-basics:3.0.0 \
   --workspace /workspace \
   --python-sast-enabled \
   --secret-scanning-enabled \

@@ -43,7 +43,7 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v2.0.3
+        uses: SocketDev/socket-basics@v3.0.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -57,7 +57,7 @@ With just your `SOCKET_SECURITY_API_KEY`, all scanning configurations are manage
 
 ### How the action is currently built
 
-When you reference `uses: SocketDev/socket-basics@v2.0.3`, GitHub Actions pulls the
+When you reference `uses: SocketDev/socket-basics@v3.0.0`, GitHub Actions pulls the
 pre-built image referenced by [`action.yml`](../action.yml). The historical multi-stage
 Docker build still matters for maintainers because it determines what lands in the
 published image:
@@ -75,7 +75,7 @@ Socket Basics from source in every workflow run.
 ### Pre-built image
 
 Starting with v2, the action pulls a pre-built image from GHCR rather than
-building from source on every run. Pinning to a specific version tag (e.g. `@v2.0.3`)
+building from source on every run. Pinning to a specific version tag (e.g. `@v3.0.0`)
 means the action starts in seconds — the image is built, integration-tested, and
 published before the release tag is ever created.
 
@@ -85,7 +85,7 @@ If you run socket-basics in other CI systems (Jenkins, GitLab, CircleCI, etc.) o
 as a standalone `docker run`, pull the pre-built image directly:
 
 ```bash
-docker pull ghcr.io/socketdev/socket-basics:2.0.3
+docker pull ghcr.io/socketdev/socket-basics:3.0.0
 ```
 
 See [Local Docker Installation](local-install-docker.md) for usage examples.
@@ -101,7 +101,7 @@ is immediately affected. We've seen this happen across the ecosystem:
   publish `:latest`/`:latest-heavy` Docker aliases as an onboarding
   convenience, but treat them as exactly that — production pipelines should
   pin an exact version or digest.)
-- **Version tags** (`@v2.0.3`) are better, but tags are mutable by default.
+- **Version tags** (`@v3.0.0`) are better, but tags are mutable by default.
   A tag can be deleted and recreated pointing at a different commit. There are
   documented cases of this happening — maliciously and accidentally.
 - **Commit SHAs** are the only truly immutable reference. A SHA cannot be
@@ -126,14 +126,14 @@ The only truly immutable reference. Dependabot keeps it current automatically.
 ```yaml
 - name: Run Socket Basics
   # Dependabot keeps this SHA up to date — see .github/dependabot.yml setup below.
-  uses: SocketDev/socket-basics@<sha>  # v2.0.3
+  uses: SocketDev/socket-basics@<sha>  # v3.0.0
   with:
     socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
 ```
 
 Get the SHA for any release:
 ```bash
-git ls-remote https://github.com/SocketDev/socket-basics refs/tags/v2.0.3
+git ls-remote https://github.com/SocketDev/socket-basics refs/tags/v3.0.0
 ```
 
 ---
@@ -145,7 +145,7 @@ enforces tag protection rules). SHA pinning is still preferable for defence
 in depth.
 
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
 ```
@@ -166,7 +166,7 @@ updates:
 ```
 
 Dependabot opens a PR for each new release, updating the SHA or version tag
-and keeping the `# v2.0.3` comment in sync. You review, approve, and merge
+and keeping the `# v3.0.0` comment in sync. You review, approve, and merge
 on your own schedule — automated upgrades with a human gate.
 
 ---
@@ -176,7 +176,7 @@ on your own schedule — automated upgrades with a human gate.
 | Strategy | Immutable? | Auto-updates | Review gate |
 |---|---|---|---|
 | `@v2` floating tag | ❌ (not published) | — | — |
-| `@v2.0.3` + Dependabot | ✅ (tag protection enforced) | Yes (weekly PR) | Yes |
+| `@v3.0.0` + Dependabot | ✅ (tag protection enforced) | Yes (weekly PR) | Yes |
 | `@<sha>` + Dependabot | ✅ always | Yes (weekly PR) | Yes |
 
 ## Basic Configuration
@@ -204,7 +204,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 
 **SAST (Static Analysis):**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     # Enable SAST for specific languages
@@ -218,7 +218,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 
 **Secret Scanning:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     secret_scanning_enabled: 'true'
@@ -230,7 +230,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 
 **Container Scanning:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     # The supported pre-built GitHub Action path currently ships without
@@ -252,7 +252,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 
 **Socket Tier 1 Reachability:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_tier_1_enabled: 'true'
@@ -261,7 +261,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 ### Output Configuration
 
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     python_sast_enabled: 'true'
@@ -299,7 +299,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run Socket Basics (changed files only)
-        uses: SocketDev/socket-basics@v2.0.3
+        uses: SocketDev/socket-basics@v3.0.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
         with:
@@ -348,7 +348,7 @@ Configure Socket Basics centrally from the [Socket Dashboard](https://socket.dev
 
 **Enable in workflow:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   env:
     GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
   with:
@@ -361,7 +361,7 @@ Configure Socket Basics centrally from the [Socket Dashboard](https://socket.dev
 > [!NOTE]
 > You can also pass credentials using environment variables instead of the `with:` section:
 > ```yaml
-> - uses: SocketDev/socket-basics@v2.0.3
+> - uses: SocketDev/socket-basics@v3.0.0
 >   env:
 >     SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_SECURITY_API_KEY }}
 >   with:
@@ -379,7 +379,7 @@ All notification integrations require Socket Enterprise.
 
 **Slack Notifications:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -391,7 +391,7 @@ All notification integrations require Socket Enterprise.
 
 **Jira Issue Creation:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -406,7 +406,7 @@ All notification integrations require Socket Enterprise.
 
 **Microsoft Teams:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -418,7 +418,7 @@ All notification integrations require Socket Enterprise.
 
 **Generic Webhook:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -430,7 +430,7 @@ All notification integrations require Socket Enterprise.
 
 **SIEM Integration:**
 ```yaml
-- uses: SocketDev/socket-basics@v2.0.3
+- uses: SocketDev/socket-basics@v3.0.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -466,7 +466,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v2.0.3
+        uses: SocketDev/socket-basics@v3.0.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -509,7 +509,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Run Full Security Scan
-        uses: SocketDev/socket-basics@v2.0.3
+        uses: SocketDev/socket-basics@v3.0.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -634,7 +634,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v2.0.3
+        uses: SocketDev/socket-basics@v3.0.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -691,7 +691,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v2.0.3
+        uses: SocketDev/socket-basics@v3.0.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -820,7 +820,7 @@ env:
 ```yaml
 steps:
   - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - Must be first
-  - uses: SocketDev/socket-basics@v2.0.3
+  - uses: SocketDev/socket-basics@v3.0.0
 ```
 
 ### PR Comments Not Appearing