Bump sample version pin to v1.6.0, automate future bumps on release

.github/workflows/bump-sample-version.yml

@@ -0,0 +1,67 @@
+# This repository has immutable releases enabled, so pinning to a full
+# release tag (e.g. `@v1.7.0`) is a secure alternative to a rolling major tag
+# (`@v1`) or a commit SHA, since the tag can't be moved or deleted once the
+# release is published. Whenever a new release is published, this workflow
+# opens (or updates) a pull request that bumps the version referenced in the
+# README.md samples to match.
+name: "Bump Sample Version"
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  bump-sample-version:
+    name: Bump README sample version
+    # Pre-releases aren't a recommended pin target for samples.
+    if: ${{ github.event.release.prerelease == false }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          ref: main
+
+      - name: Bump pinned action version in README
+        id: bump-version
+        env:
+          NEW_VERSION: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+
+          if [[ ! "$NEW_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::warning::Release tag '$NEW_VERSION' is not a full 'vX.Y.Z' version. Skipping sample update."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Only full semantic version pins (e.g. "@v1.2.3") are handled here;
+          # rolling tags like "@v1" are left untouched.
+          sed -i -E "s#(advanced-security/set-codeql-language-matrix@)v[0-9]+\.[0-9]+\.[0-9]+#\1${NEW_VERSION}#g" README.md
+
+          if git diff --quiet -- README.md; then
+            echo "README.md already references ${NEW_VERSION}. Nothing to do."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            git diff -- README.md
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create Pull Request
+        if: steps.bump-version.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "docs: bump sample version to ${{ github.event.release.tag_name }}"
+          title: "docs: bump sample version to ${{ github.event.release.tag_name }}"
+          body: |
+            Automated PR to bump the pinned action version referenced in the README.md samples to the latest release [`${{ github.event.release.tag_name }}`](${{ github.event.release.html_url }}).
+
+            Since this repository has immutable releases enabled, pinning samples to a full version tag (e.g. `@${{ github.event.release.tag_name }}`) is a secure, easy-to-read alternative to a rolling major tag like `@v1` or a full commit SHA.
+          branch: chore/bump-sample-version
+          base: main
+          delete-branch: true
+          labels: documentation

CONTRIBUTING.md

@@ -9,4 +9,8 @@ To do this just checkout `main` given the latest version, force-create a new ann
 ```
 git tag -fa v1 -m "Updating v1 to 1.2.2"
 git push origin v1 --force
-```
+```
+
+## Keeping sample version references up to date
+
+The [README.md](./README.md) samples pin to a full release version (e.g. `advanced-security/set-codeql-language-matrix@v1.6.0`). The [Bump Sample Version](./.github/workflows/bump-sample-version.yml) workflow automatically opens a pull request to update these references whenever a new (non-prerelease) release is published, so no manual action is required.

README.md

@@ -44,7 +44,7 @@ jobs:
     steps:
       - name: Get languages from repo
         id: set-matrix
-        uses: advanced-security/set-codeql-language-matrix@v1
+        uses: advanced-security/set-codeql-language-matrix@v1.6.0
         with:
           access-token: ${{ secrets.GITHUB_TOKEN }}
           endpoint: ${{ github.event.repository.languages_url }}
@@ -90,6 +90,12 @@ jobs:
         category: "/language:${{matrix.language}}"
 ```      
 
+### Pinning a version
+
+The samples above pin to a full release version (e.g. `@v1.6.0`) rather than a rolling major tag (e.g. `@v1`). This repository has immutable releases enabled, so a full version tag can't be moved or deleted once it's published, making it a secure alternative to pinning by commit SHA while remaining easy to read.
+
+A [workflow](./.github/workflows/bump-sample-version.yml) in this repository automatically opens a pull request to bump the version referenced in these samples whenever a new release is published.
+
 ### Excluding CodeQL Languages
 It's possible you may choose to exclude specific languages from your CodeQL scans. In that case, use the `exclude` input.
 
@@ -102,7 +108,7 @@ Example:
     steps:
       - name: Get languages from repo
         id: set-matrix
-        uses: advanced-security/set-codeql-language-matrix@v1
+        uses: advanced-security/set-codeql-language-matrix@v1.6.0
         with:
           access-token: ${{ secrets.GITHUB_TOKEN }}
           endpoint: ${{ github.event.repository.languages_url }}
@@ -125,7 +131,7 @@ If you want to override this behavior and use manual build mode for specific lan
     steps:
       - name: Get languages from repo
         id: set-matrix
-        uses: advanced-security/set-codeql-language-matrix@v1
+        uses: advanced-security/set-codeql-language-matrix@v1.6.0
         with:
           access-token: ${{ secrets.GITHUB_TOKEN }}
           endpoint: ${{ github.event.repository.languages_url }}
@@ -148,7 +154,7 @@ Set the `standard-language-names` input to `'true'` to have this action emit the
     steps:
       - name: Get languages from repo
         id: set-matrix
-        uses: advanced-security/set-codeql-language-matrix@v1
+        uses: advanced-security/set-codeql-language-matrix@v1.6.0
         with:
           access-token: ${{ secrets.GITHUB_TOKEN }}
           endpoint: ${{ github.event.repository.languages_url }}