docs: pin actions by SHA, document tag policy, add a pin check

.github/PULL_REQUEST_TEMPLATE.md

@@ -16,6 +16,6 @@ Outputs renamed or removed: none
 ## Checks
 
 - [ ] Action smoke test passes on this PR
-- [ ] Docs and `examples/` use `bawbel/integrations@v1`
+- [ ] Docs and `examples/` pin every action and `rev` by commit SHA (`python scripts/check_pins.py`)
 - [ ] README and `examples/` match any changed action input or output
 - [ ] No em dashes

.github/workflows/action-smoke.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Run bawbel/integrations@v1 on a fixture with a known finding
         id: bawbel
         # Deliberately unpinned: this job tests the public v1 tag that users copy.
-        uses: bawbel/integrations@v1
+        uses: bawbel/integrations@v1 # pin-exempt: tests the public moving tag that users copy
         with:
           path: test_skill.md
           recursive: "false"

.github/workflows/pins.yml

@@ -0,0 +1,26 @@
+# Every action and pre-commit rev in this repo is pinned by commit SHA (RELEASING.md).
+# fetch-depth 0 brings the tags, which the checker needs to compare a SHA with its release.
+name: Pins
+
+on:
+  pull_request:
+  push:
+    branches: [develop, main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pins:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+
+      - name: Every action and rev is pinned by commit SHA
+        run: python3 scripts/check_pins.py
+
+      - name: Pin checker tests
+        run: python3 -m unittest discover -s tests -p "test_check_pins.py"

.pre-commit-hooks.yaml

@@ -5,7 +5,7 @@
 #
 #   repos:
 #     - repo: https://github.com/bawbel/bawbel-integrations
-#       rev: v1
+#       rev: <release-commit-sha>  # frozen: <release tag>
 #       hooks:
 #         - id: bawbel-scan
 

README.md

@@ -31,8 +31,10 @@ Scan on every push and pull request. Findings appear as inline PR annotations
 in the GitHub Security tab via SARIF upload. Blocks merges on CRITICAL or HIGH
 findings.
 
-The action reference is `bawbel/integrations@v1`. Use that name, not
-`bawbel/scanner` or `bawbel/bawbel-integrations`.
+The action reference is `bawbel/integrations`. Use that name, not
+`bawbel/scanner` or `bawbel/bawbel-integrations`. Pin it to a commit SHA and write the
+release in a trailing comment, as below: a tag can be moved, a commit cannot.
+See [Pinning and releases](#pinning-and-releases).
 
 ```yaml
 # .github/workflows/bawbel.yml
@@ -46,12 +48,12 @@ jobs:
       security-events: write
       contents: read
     steps:
-      - uses: actions/checkout@v4
-      - uses: bawbel/integrations@v1
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: bawbel/integrations@ee77de3c8fb927a41ca9d8d5f51be22215978d14 # v1.1.0
         with:
           path: .
           fail-on-severity: high
-      - uses: github/codeql-action/upload-sarif@v3
+      - uses: github/codeql-action/upload-sarif@ce5e7eeac396d720fe2d802714996c8ce561e311 # v3.39.0
         if: always()
         with:
           sarif_file: bawbel-results.sarif
@@ -70,6 +72,21 @@ jobs:
 
 See [`action.yml`](action.yml) for full input/output reference.
 
+### Pinning and releases
+
+Releases are tagged `vMAJOR.MINOR.PATCH` and a release tag is never moved. `v1` is a moving
+tag that points at the newest `v1.x.y` release. Use it to try the action, not in a pipeline
+you rely on. The policy and the release steps are in [RELEASING.md](RELEASING.md).
+
+To pin, take the commit of the release you want and write the release in a comment:
+
+```bash
+gh api repos/bawbel/integrations/commits/v1.1.0 --jq .sha
+```
+
+Dependabot with the `github-actions` ecosystem keeps SHA pins current. This repo uses it
+for its own workflows (`.github/dependabot.yml`).
+
 ---
 
 ## VS Code Extension
@@ -121,11 +138,17 @@ Block malicious skills at the commit boundary — before they reach CI.
 pre-commit automatically installs `bawbel-scanner` in an isolated virtualenv.
 No manual `pip install` needed.
 
+No release contains these hooks yet. `.pre-commit-hooks.yaml` was added after v1.1.0, so
+`rev: v1` and `rev: v1.1.0` fail with
+`InvalidManifestError: .pre-commit-hooks.yaml is not a file`. Until a release contains
+it, use Option 2. After that, set `rev` to the commit SHA of that release, with the tag in a
+comment as below.
+
 ```yaml
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/bawbel/bawbel-integrations
-    rev: v1
+    rev: <release-commit-sha>  # frozen: <release tag>
     hooks:
       - id: bawbel-scan          # pattern engine only (~15ms per file)
 ```
@@ -135,7 +158,7 @@ All engines (YARA + Semgrep + Magika — slower, more thorough):
 ```yaml
 repos:
   - repo: https://github.com/bawbel/bawbel-integrations
-    rev: v1
+    rev: <release-commit-sha>  # frozen: <release tag>
     hooks:
       - id: bawbel-scan-all
 ```
@@ -145,7 +168,7 @@ Custom severity threshold:
 ```yaml
 repos:
   - repo: https://github.com/bawbel/bawbel-integrations
-    rev: v1
+    rev: <release-commit-sha>  # frozen: <release tag>
     hooks:
       - id: bawbel-scan
         args: ["--fail-on-severity", "critical"]

RELEASING.md

@@ -0,0 +1,67 @@
+# Releases and pinning
+
+How `bawbel/integrations` is released and what its tags mean. Maintainers cut releases.
+Nothing here runs by itself.
+
+## Tags
+
+| Tag | Meaning | Moves? |
+|---|---|---|
+| `vX.Y.Z` (for example `v1.1.0`) | One release | Never. A release tag is not moved, deleted, or re-pointed. A bad release is fixed by a new patch release. |
+| `vX` (for example `v1`) | The newest `vX.Y.Z` release of that major version | Yes, and only as described below |
+
+`v1` moves only to a `v1.Y.Z` release tag, and only after the release steps below have passed.
+It never moves to a commit that is not a tagged release, and never to a different major
+version. If a release turns out to be bad, `v1` moves back to the last good release tag, a
+patch release follows, and the release notes say so.
+
+A change that breaks existing workflows is a new major version (`v2`), and `v1` stays where
+it is. That covers renaming or removing an input or an output, and changing a default so that
+a passing workflow fails or the other way round.
+
+## Pinning, for people who use the action
+
+Pin to the commit SHA of a release and write the release in a trailing comment:
+
+```yaml
+- uses: bawbel/integrations@ee77de3c8fb927a41ca9d8d5f51be22215978d14 # v1.1.0
+```
+
+```bash
+gh api repos/bawbel/integrations/commits/v1.1.0 --jq .sha
+```
+
+`v1` is for trying the action. It changes under you by design.
+
+## This repository's own workflows
+
+Every `uses:` and `rev:` in `.github/workflows/`, `README.md`, `examples/`,
+`bawbel_hooks/README.md`, and `.pre-commit-hooks.yaml` is a 40-character commit SHA with the
+release in a trailing comment. `scripts/check_pins.py` enforces that in CI (the `Pins`
+workflow). It also checks that a SHA written for this repo's own action is the commit its
+comment's tag points to. It does not compare third-party SHAs with their upstream tags.
+
+There is one exception: `.github/workflows/action-smoke.yml` runs the public `v1` tag on
+purpose, because it tests what a user who copies `@v1` gets. The line carries
+`# pin-exempt: <reason>`.
+
+A component that no release contains yet is documented with the placeholder
+`<release-commit-sha>`. The checker lists each one so the release PR can fill them in.
+Dependabot (`.github/dependabot.yml`) updates the pins in workflows every week. It does not
+edit the README or `examples/`.
+
+## Cutting a release
+
+1. `develop` is green: `Action tests (working tree)`, `Gate lint action tests (working tree)`
+   and `Pins`. The README matches `action.yml` and `gate-lint/action.yml`.
+2. Promote `develop` to `main` with a pull request that a person reviews.
+3. Tag the merge commit on `main` as `vX.Y.Z` and push the tag. Write the release notes:
+   what changed, and anything that makes a workflow behave differently.
+4. Move the major tag to it:
+   `git tag -f v1 vX.Y.Z && git push --force origin refs/tags/v1`
+5. Run `Action smoke test` from the Actions tab. It uses the public `v1`. If it fails, move
+   `v1` back to the previous release, then fix forward with a patch release.
+6. Open a docs pull request that sets the SHA in `README.md` and `examples/` to the new
+   release, and fills in any `<release-commit-sha>` placeholder. Run
+   `python scripts/check_pins.py` first: it names every line to change and rejects a SHA that
+   does not match its tag.

bawbel_hooks/README.md

@@ -12,11 +12,17 @@ Add to `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/bawbel/bawbel-integrations
-    rev: v1
+    rev: <release-commit-sha>  # frozen: <release tag>
     hooks:
       - id: bawbel-scan
 ```
 
+No release contains these hooks yet. `.pre-commit-hooks.yaml` was added after v1.1.0, so
+`rev: v1` and `rev: v1.1.0` fail with
+`InvalidManifestError: .pre-commit-hooks.yaml is not a file`. Until a release contains
+it, use Option 2. After that, set `rev` to the commit SHA of that release, with the tag in a
+comment as below.
+
 That's it. On every `git commit`, Bawbel will scan your staged
 `.md`, `.yaml`, and `.json` files for AVE vulnerabilities.
 

examples/basic.yml

@@ -6,8 +6,8 @@ jobs:
   scan:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: bawbel/integrations@v1
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: bawbel/integrations@ee77de3c8fb927a41ca9d8d5f51be22215978d14 # v1.1.0
         with:
           path: .
           fail-on-severity: high

examples/sarif.yml

@@ -9,18 +9,18 @@ jobs:
       security-events: write
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
 
       - name: Scan for AVE vulnerabilities
-        uses: bawbel/integrations@v1
+        uses: bawbel/integrations@ee77de3c8fb927a41ca9d8d5f51be22215978d14 # v1.1.0
         id: bawbel
         with:
           path: .
           fail-on-severity: none   # don't fail — upload first
           format: sarif
 
       - name: Upload to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@ce5e7eeac396d720fe2d802714996c8ce561e311 # v3.39.0
         if: always()
         with:
           sarif_file: ${{ steps.bawbel.outputs.sarif-file }}