ci: least-privilege permissions and env-only inputs across workflows

Every workflow now sets top-level permissions: {} and grants scopes per
job, matching .github/workflows/README.md (only sync.yml and drift-check
did before). label-sync passes the PR number through env, creates labels
only when missing instead of recoloring them with --force, drops the
unneeded checkout, and skips fork PRs whose token cannot label.
release-drafter is pinned to a commit SHA (v7.10.0) with job-level
permissions. The drift-check and release-doc-sync composite actions route
inputs and step outputs through env instead of expanding expressions into
shell source.

The sticky-issue step now hands its issues token to the CLI explicitly
(new --issues-token / DRIFT_CHECK_ISSUES_TOKEN), so the clone PAT and the
workflow GITHUB_TOKEN each do their own job.

tests/test_workflow_hygiene.py and an extra composite-action test enforce
both rules going forward.

Closes #117

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

Author: TMHSDigital

.github/actions/drift-check/action.yml

@@ -4,7 +4,7 @@
 #
 # Reusable action invoked by:
 #   - the meta-repo's own drift-check.yml workflow (mode: all)
-#   - tool-repo validate.yml workflows (mode: self) — wired up in Session D
+#   - tool-repo validate.yml workflows (mode: self) - wired up in Session D
 #
 # What it does:
 #   1. Checks out THIS action's repo (TMHSDigital/Developer-Tools-Directory),
@@ -87,14 +87,14 @@ runs:
     # a known path. Use a dedicated subdirectory so we don't clobber the
     # caller's own checkout (which lives at GITHUB_WORKSPACE).
     - name: Checkout drift checker
-      uses: actions/checkout@v5
+      uses: actions/checkout@v7
       with:
         repository: TMHSDigital/Developer-Tools-Directory
         ref: ${{ inputs.meta-repo-ref }}
         path: .drift-checker
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ inputs.python-version }}
 
@@ -105,7 +105,7 @@ runs:
         if [ -f requirements.txt ]; then
           pip install -r requirements.txt
         else
-          echo "no requirements.txt — drift_check is stdlib-only, skipping"
+          echo "no requirements.txt - drift_check is stdlib-only, skipping"
         fi
 
     - name: Resolve meta-commit
@@ -120,17 +120,23 @@ runs:
       id: run
       shell: bash
       working-directory: .drift-checker
+      # Inputs reach the shell only through env, never through expression
+      # expansion inside run:, per .github/workflows/README.md.
       env:
         DRIFT_CHECK_TOKEN: ${{ inputs.github-token }}
+        INPUT_MODE: ${{ inputs.mode }}
+        INPUT_CALLER_PATH: ${{ inputs.caller-path }}
+        INPUT_FORMAT: ${{ inputs.format }}
+        META_SHA: ${{ steps.meta.outputs.sha }}
       run: |
         set +e
         EXTRA_ARGS=()
-        if [ "${{ inputs.mode }}" = "all" ]; then
+        if [ "$INPUT_MODE" = "all" ]; then
           EXTRA_ARGS+=(--all)
-        elif [ "${{ inputs.mode }}" = "self" ]; then
-          EXTRA_ARGS+=(--local "$GITHUB_WORKSPACE/${{ inputs.caller-path }}")
+        elif [ "$INPUT_MODE" = "self" ]; then
+          EXTRA_ARGS+=(--local "$GITHUB_WORKSPACE/$INPUT_CALLER_PATH")
         else
-          echo "::error::invalid mode: ${{ inputs.mode }} (expected 'self' or 'all')"
+          echo "::error::invalid mode: $INPUT_MODE (expected 'self' or 'all')"
           exit 2
         fi
 
@@ -140,7 +146,7 @@ runs:
           "${EXTRA_ARGS[@]}" \
           --format json \
           --output /tmp/drift-findings.json \
-          --meta-commit "${{ steps.meta.outputs.sha }}"
+          --meta-commit "$META_SHA"
         FINDINGS_RC=$?
 
         # Extract counts (default to 0 if jq missing or file absent).
@@ -155,15 +161,15 @@ runs:
 
         # Now render the user-requested format (which writes to step summary
         # automatically when format=gh-summary).
-        if [ "${{ inputs.format }}" != "json" ]; then
+        if [ "$INPUT_FORMAT" != "json" ]; then
           python scripts/drift_check/cli.py \
             "${EXTRA_ARGS[@]}" \
-            --format "${{ inputs.format }}" \
-            --meta-commit "${{ steps.meta.outputs.sha }}"
+            --format "$INPUT_FORMAT" \
+            --meta-commit "$META_SHA"
         fi
 
         # Tool errors (rc=2) abort immediately and skip the sticky-issue
-        # step — there's nothing meaningful to publish if the checker
+        # step - there's nothing meaningful to publish if the checker
         # itself failed. Drift findings (rc=1) are NOT propagated here so
         # the optional sticky-issue step still runs; the final
         # "Propagate checker exit code" step at the end of this composite
@@ -185,27 +191,32 @@ runs:
         # permissions block is the reliable source. issues-token defaults
         # to github-token for backward compatibility.
         DRIFT_CHECK_TOKEN: ${{ inputs.github-token }}
+        # The CLI writes the sticky issue with DRIFT_CHECK_ISSUES_TOKEN and
+        # clones with DRIFT_CHECK_TOKEN, so each token does one job.
+        DRIFT_CHECK_ISSUES_TOKEN: ${{ inputs.issues-token != '' && inputs.issues-token || inputs.github-token }}
         GH_TOKEN: ${{ inputs.issues-token != '' && inputs.issues-token || inputs.github-token }}
+        INPUT_MODE: ${{ inputs.mode }}
+        INPUT_CALLER_PATH: ${{ inputs.caller-path }}
+        META_SHA: ${{ steps.meta.outputs.sha }}
       run: |
         set +e
-        ISSUES_TOKEN="${{ inputs.issues-token != '' && inputs.issues-token || inputs.github-token }}"
-        if [ -z "$ISSUES_TOKEN" ]; then
+        if [ -z "$DRIFT_CHECK_ISSUES_TOKEN" ]; then
           echo "::warning::update-sticky-issue=true but no issues-token / github-token provided; skipping"
           echo "action=skipped" >> "$GITHUB_OUTPUT"
           exit 0
         fi
         EXTRA_ARGS=()
-        if [ "${{ inputs.mode }}" = "all" ]; then
+        if [ "$INPUT_MODE" = "all" ]; then
           EXTRA_ARGS+=(--all)
         else
-          EXTRA_ARGS+=(--local "$GITHUB_WORKSPACE/${{ inputs.caller-path }}")
+          EXTRA_ARGS+=(--local "$GITHUB_WORKSPACE/$INPUT_CALLER_PATH")
         fi
         OUT=$(python scripts/drift_check/cli.py \
           "${EXTRA_ARGS[@]}" \
           --format json \
           --output /dev/null \
           --update-sticky-issue \
-          --meta-commit "${{ steps.meta.outputs.sha }}" 2>&1)
+          --meta-commit "$META_SHA" 2>&1)
         RC=$?
         echo "$OUT"
         # Parse the "Sticky issue: <action>" line emitted by cli.py.
@@ -228,16 +239,17 @@ runs:
       # don't mask the earlier failure that already failed the action.
       if: always()
       shell: bash
+      env:
+        RC: ${{ steps.run.outputs.exit-code }}
       run: |
-        RC="${{ steps.run.outputs.exit-code }}"
         if [ -z "$RC" ]; then
           echo "drift checker did not run; nothing to propagate"
           exit 0
         fi
         echo "drift checker exit code: $RC"
         case "$RC" in
           0) echo "no drift detected" ;;
-          1) echo "::error::drift detected — failing job per composite-action contract" ;;
+          1) echo "::error::drift detected - failing job per composite-action contract" ;;
           2) echo "::error::tool error in drift checker" ;;
           *) echo "::warning::unexpected exit code from drift checker: $RC" ;;
         esac

.github/actions/release-doc-sync/action.yml

@@ -97,7 +97,7 @@ runs:
     # The sync script lives in this repo. Whether the caller is the meta-repo
     # itself or a tool repo, we always need the script at a known path.
     #
-    # actions/checkout@v5 enforces that `path:` resolves UNDER GITHUB_WORKSPACE
+    # actions/checkout@v7 enforces that `path:` resolves UNDER GITHUB_WORKSPACE
     # (it rejects absolute or out-of-tree paths with "Repository path '...' is
     # not under '...'"). So we check out to a dotted subdirectory and rely on
     # the explicit "Clean up workspace checkout" step below to remove it
@@ -111,14 +111,14 @@ runs:
     # and v1.8.2 introduced the cleanup-step pattern that actually works.
     # Regression-tested in tests/test_release_doc_sync.py.
     - name: Checkout release-doc-sync script
-      uses: actions/checkout@v5
+      uses: actions/checkout@v7
       with:
         repository: TMHSDigital/Developer-Tools-Directory
         ref: ${{ inputs.meta-repo-ref }}
         path: .release-doc-sync
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ inputs.python-version }}
 
@@ -166,4 +166,4 @@ runs:
       if: always()
       shell: bash
       run: |
-        rm -rf "${{ github.workspace }}/.release-doc-sync"
+        rm -rf "$GITHUB_WORKSPACE/.release-doc-sync"

.github/workflows/README.md

@@ -115,5 +115,6 @@ When a third-party action releases a new version:
 
 ## Known follow-ups
 
-- `release-drafter/release-drafter@v6` in `release-drafter.yml` is still pinned by major tag. It runs under `pull_request_target` but does not check out PR code, so the fork-RCE vector does not apply. SHA-pinning tracked for v1.7.
+- `release-drafter/release-drafter` in `release-drafter.yml` is SHA-pinned (v7.10.0). It runs under `pull_request_target` but never checks out PR code. Dependabot proposes SHA bumps.
+- Both conventions above are enforced by `tests/test_workflow_hygiene.py` (workflows) and `tests/test_composite_action_shape.py` (composite actions).
 - `peter-evans/create-pull-request` in `sync.yml` is SHA-pinned. Update as releases land.

.github/workflows/codeql.yml

@@ -8,13 +8,14 @@ on:
   schedule:
     - cron: "0 6 * * 1"
 
-permissions:
-  actions: read
-  contents: read
-  security-events: write
+permissions: {}
 
 jobs:
   analyze:
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
     name: Analyze Python
     runs-on: ubuntu-latest
     strategy:

.github/workflows/dependency-review.yml

@@ -4,12 +4,13 @@ on:
   pull_request:
     branches: [main]
 
-permissions:
-  contents: read
-  pull-requests: write
+permissions: {}
 
 jobs:
   dependency-review:
+    permissions:
+      contents: read
+      pull-requests: write
     name: Audit dependencies
     runs-on: ubuntu-latest
     steps:

.github/workflows/drift-check.yml

@@ -33,6 +33,8 @@ on:
       - .github/actions/drift-check/**
       - .github/workflows/drift-check.yml
 
+permissions: {}
+
 concurrency:
   # Coalesce queued runs of the same trigger; do NOT cancel an in-flight
   # check (the sticky-issue upsert is non-idempotent during the gh edit
@@ -57,8 +59,8 @@ jobs:
         with:
           mode: all
           format: gh-summary
-          # DRIFT_CHECK_TOKEN provides cross-repo Contents:Read on the 9
-          # tool repos. GITHUB_TOKEN is the fallback for self-only runs
+          # DRIFT_CHECK_TOKEN provides cross-repo Contents:Read on every
+          # live tool repo in registry.json. GITHUB_TOKEN is the fallback for self-only runs
           # where remote sparse-checkout is not needed.
           github-token: ${{ secrets.DRIFT_CHECK_TOKEN || secrets.GITHUB_TOKEN }}
           # GITHUB_TOKEN with the workflow's issues:write permission is
@@ -74,8 +76,13 @@ jobs:
       - name: Report outcome
         if: always()
         shell: bash
+        env:
+          EXIT_CODE: ${{ steps.drift.outputs.exit-code }}
+          ERRORS: ${{ steps.drift.outputs.error-count }}
+          WARNINGS: ${{ steps.drift.outputs.warning-count }}
+          STICKY: ${{ steps.drift.outputs.sticky-issue-action }}
         run: |
-          echo "exit-code: ${{ steps.drift.outputs.exit-code }}"
-          echo "errors:    ${{ steps.drift.outputs.error-count }}"
-          echo "warnings:  ${{ steps.drift.outputs.warning-count }}"
-          echo "sticky:    ${{ steps.drift.outputs.sticky-issue-action }}"
+          echo "exit-code: $EXIT_CODE"
+          echo "errors:    $ERRORS"
+          echo "warnings:  $WARNINGS"
+          echo "sticky:    $STICKY"

.github/workflows/label-sync.yml

@@ -4,29 +4,25 @@ on:
   pull_request:
     types: [opened, synchronize]
 
-permissions:
-  contents: read
-  pull-requests: write
+permissions: {}
 
 jobs:
   label:
     name: Auto-label by path
     runs-on: ubuntu-latest
+    # Fork PRs get a read-only token, so labeling cannot succeed there.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
-      - uses: actions/checkout@v7
-
-      - name: Get changed files
-        id: changed
-        run: |
-          FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only)
-          echo "files<<EOF" >> "$GITHUB_OUTPUT"
-          echo "$FILES" >> "$GITHUB_OUTPUT"
-          echo "EOF" >> "$GITHUB_OUTPUT"
+      - name: Apply labels by changed path
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Apply labels
+          GH_REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
+          FILES="$(gh pr diff "$PR_NUMBER" --name-only)"
           LABELS=""
 
           if echo "$FILES" | grep -q "^standards/"; then
@@ -49,15 +45,17 @@ jobs:
             LABELS="$LABELS ci"
           fi
 
-          if [ -n "$LABELS" ]; then
-            for label in $LABELS; do
-              gh label create "$label" --force --color "ededed" 2>/dev/null || true
-              gh pr edit ${{ github.event.pull_request.number }} --add-label "$label"
-            done
-            echo "Applied labels:$LABELS"
-          else
+          if [ -z "$LABELS" ]; then
             echo "No labels to apply"
+            exit 0
           fi
-        env:
-          FILES: ${{ steps.changed.outputs.files }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+          EXISTING="$(gh label list --limit 200 --json name --jq '.[].name')"
+          for label in $LABELS; do
+            # Create only when missing, so existing label colors are kept.
+            if ! printf '%s\n' "$EXISTING" | grep -qx "$label"; then
+              gh label create "$label" --color "ededed" || true
+            fi
+            gh pr edit "$PR_NUMBER" --add-label "$label"
+          done
+          echo "Applied labels:$LABELS"

.github/workflows/pages.yml

@@ -9,16 +9,17 @@ on:
       - "registry.json"
   workflow_dispatch:
 
-permissions:
-  pages: write
-  id-token: write
+permissions: {}
 
 concurrency:
   group: pages
   cancel-in-progress: true
 
 jobs:
   deploy:
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.github/workflows/release-drafter.yml

@@ -6,15 +6,18 @@ on:
   pull_request_target:
     types: [opened, reopened, synchronize]
 
-permissions:
-  contents: write
-  pull-requests: write
+permissions: {}
 
 jobs:
   update-release-draft:
     name: Draft release notes
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
-      - uses: release-drafter/release-drafter@v7
+      # Third-party action under pull_request_target: pinned to a commit SHA
+      # (see .github/workflows/README.md). It never checks out PR code.
+      - uses: release-drafter/release-drafter@978bb0b30c5ee8cdd332ced253758157150d43f0 # v7.10.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -5,15 +5,16 @@ on:
     branches: [main]
   workflow_dispatch:
 
-permissions:
-  contents: read
+permissions: {}
 
 concurrency:
   group: release-${{ github.workflow }}
   cancel-in-progress: false
 
 jobs:
   check-version:
+    permissions:
+      contents: read
     name: Check VERSION vs latest tag
     runs-on: ubuntu-latest
     if: "!contains(github.event.head_commit.message, '[skip ci]')"