Implement checkout reference validation and enhance README documentation

- Added a Python script to check for 'with.ref' specification in all actions/checkout usages, ensuring consistent checkout behavior across workflows.
- Introduced a new lint-workflows.yml file to automate the validation process during push and pull request events.
- Updated the README to include new security requirements and examples for specifying 'with.ref' in workflows, reinforcing best practices for GitHub Actions.

Author: kubabuczak

.github/README.md

@@ -16,8 +16,12 @@ GitHub's `pull_request` event doesn't expose secrets to fork PRs (for security).
 ### Security Requirements
 
 1. **Always use `approval-gate.yml`** as a dependency for jobs needing secrets
-2. **Always use `target-checkout`** action to checkout the correct PR commit (not the base branch)
-3. **Always pass the approval gate's `commit-sha`** to prevent testing unapproved code:
+2. **Always specify `with.ref`** on all `actions/checkout` steps (enforced by `lint-workflows.yml`)
+3. **Always pass the approval gate's `commit-sha`** to prevent testing unapproved code
+
+### Checkout Patterns
+
+**For workflows using approval-gate** (recommended for `pull_request_target`):
 
 ```yaml
 jobs:
@@ -27,9 +31,23 @@ jobs:
   build:
     needs: approval-gate
     steps:
-      - uses: ./.github/actions/target-checkout
+      - uses: actions/checkout@v6
         with:
           ref: ${{ needs.approval-gate.outputs.commit-sha }}
 ```
 
+**For simpler workflows** (e.g., `pull_request` or `push` triggers):
+
+```yaml
+# Preferred: Define ref once at workflow level, reuse in all jobs
+env:
+  CHECKOUT_REF: ${{ github.ref }}
+jobs:
+  build:
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ env.CHECKOUT_REF }}
+```
+
 > ⚠️ Without these safeguards, a malicious commit could be added after approval but before execution.

.github/scripts/check-checkout-ref.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""
+Check that all actions/checkout usages have 'with.ref' specified.
+
+This ensures consistent and explicit checkout behavior across all workflows.
+"""
+
+import sys
+from pathlib import Path
+
+import yaml
+
+
+def check_workflow_file(filepath: Path) -> list[dict]:
+    """
+    Check a workflow file for actions/checkout usages without 'with.ref'.
+
+    Returns a list of violations.
+    """
+    violations = []
+
+    with open(filepath, "r") as f:
+        try:
+            data = yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            print(f"Warning: Failed to parse {filepath}: {e}")
+            return []
+
+    if not data or "jobs" not in data:
+        return []
+
+    for job_name, job in data["jobs"].items():
+        steps = job.get("steps", [])
+        for i, step in enumerate(steps):
+            uses = step.get("uses", "")
+            if "actions/checkout" in uses:
+                with_block = step.get("with", {})
+                has_ref = isinstance(with_block, dict) and "ref" in with_block
+
+                if not has_ref:
+                    violations.append({
+                        "file": str(filepath),
+                        "job": job_name,
+                        "step": i,
+                        "uses": uses,
+                    })
+
+    return violations
+
+
+def main():
+    workflows_dir = Path(".github/workflows")
+
+    if not workflows_dir.exists():
+        print("Error: .github/workflows directory not found")
+        sys.exit(1)
+
+    all_violations = []
+
+    for pattern in ("*.yml", "*.yaml"):
+        for workflow_file in sorted(workflows_dir.glob(pattern)):
+            all_violations.extend(check_workflow_file(workflow_file))
+
+    if all_violations:
+        print("❌ Found actions/checkout usages without 'with.ref' specified:\n")
+        for v in all_violations:
+            print(f"  {v['file']}")
+            print(f"    Job: {v['job']}, Step: {v['step']}")
+            print(f"    Uses: {v['uses']}\n")
+        print(f"Total violations: {len(all_violations)}")
+        print("\nAll actions/checkout steps should specify 'with.ref' to ensure")
+        print("consistent and explicit checkout behavior.")
+        print("\nSee .github/README.md for security requirements and examples.")
+        sys.exit(1)
+    else:
+        print("✅ All actions/checkout usages have 'with.ref' specified")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/lint-workflows.yml

@@ -0,0 +1,32 @@
+name: Lint Workflows
+permissions:
+  contents: read
+on:
+  push:
+    paths:
+      - '.github/workflows/**'
+      - '.github/scripts/**'
+  pull_request:
+    paths:
+      - '.github/workflows/**'
+      - '.github/scripts/**'
+
+jobs:
+  check-checkout-ref:
+    name: Check actions/checkout has ref specified
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Check all actions/checkout have ref specified
+        run: python .github/scripts/check-checkout-ref.py