Harden reusable workflows and introduce v1 versioning

.github/workflows/CheckCompatBounds.yml

@@ -55,6 +55,8 @@ jobs:
     if: "${{ !github.event.pull_request.draft || inputs.run-on-draft }}"
     runs-on: "ubuntu-latest"
     timeout-minutes: ${{ inputs.timeout-minutes }}
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/CompatHelper.yml

@@ -18,6 +18,9 @@ on:
 jobs:
   CompatHelper:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - name: Check if Julia is already available in the PATH
         id: julia_in_path
@@ -62,6 +65,14 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.COMPATHELPER_PAT || secrets.GITHUB_TOKEN }}
       - name: "Run CompatHelper"
+        shell: julia --color=yes {0}
+        env:
+          # Use COMPATHELPER_PAT if available so that pushes trigger CI workflows.
+          # The built-in GITHUB_TOKEN can't trigger other workflows
+          # (see https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow).
+          GITHUB_TOKEN: ${{ secrets.COMPATHELPER_PAT || secrets.GITHUB_TOKEN }}
+          LOCALREGISTRY: ${{ inputs.localregistry }}
+          TOKEN_OWNER: ${{ steps.token-owner.outputs.login }}
         run: |
           import CompatHelper
           import LibGit2
@@ -83,8 +94,9 @@ jobs:
               name = "General",
             )
           ]
-          if !isempty("${{ inputs.localregistry }}")
-            registry_urls = split("${{ inputs.localregistry }}", "\n") .|> string
+          localregistry = get(ENV, "LOCALREGISTRY", "")
+          if !isempty(localregistry)
+            registry_urls = split(localregistry, "\n") .|> string
             for registry_url in registry_urls
               isempty(registry_url) && continue
               registry_name = registry_name_from_url(registry_url)
@@ -94,14 +106,8 @@ jobs:
             end
           end
           subdirs = ["", "docs", "examples", "test"]
-          token_owner = "${{ steps.token-owner.outputs.login }}"
+          token_owner = get(ENV, "TOKEN_OWNER", "")
           ci_cfg = isempty(token_owner) ?
               CompatHelper.GitHubActions() :
               CompatHelper.GitHubActions(; username=token_owner)
           CompatHelper.main(ENV, ci_cfg; registries, subdirs, bump_version=true)
-        shell: julia --color=yes {0}
-        env:
-          # Use COMPATHELPER_PAT if available so that pushes trigger CI workflows.
-          # The built-in GITHUB_TOKEN can't trigger other workflows
-          # (see https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow).
-          GITHUB_TOKEN: ${{ secrets.COMPATHELPER_PAT || secrets.GITHUB_TOKEN }}

.github/workflows/Documentation.yml

@@ -75,14 +75,19 @@ jobs:
     name: "Build and Deploy Documentation"
     continue-on-error: ${{ inputs.continue-on-error || inputs.julia-version == 'nightly' }}
     runs-on: "${{ inputs.self-hosted && 'self-hosted' || inputs.os }}"
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v4
 
       - name: "Install apt packages"
         if: "${{ inputs.apt-packages != '' && runner.os == 'Linux' }}"
+        env:
+          APT_PACKAGES: ${{ inputs.apt-packages }}
         run: |
           sudo apt-get update
-          sudo apt-get install -y ${{ inputs.apt-packages }}
+          # shellcheck disable=SC2086
+          sudo apt-get install -y $APT_PACKAGES
 
       - name: "Setup Julia ${{ inputs.julia-version }}"
         uses: julia-actions/setup-julia@v2
@@ -97,21 +102,27 @@ jobs:
       - name: "Export extra environment variables"
         if: "${{ inputs.extra-env != '' }}"
         shell: "bash"
+        env:
+          EXTRA_ENV: ${{ inputs.extra-env }}
         run: |
-          echo "${{ inputs.extra-env }}" >> "$GITHUB_ENV"
+          printf '%s\n' "$EXTRA_ENV" >> "$GITHUB_ENV"
 
       - name: Setup project
         shell: "bash"
+        env:
+          DOC_PREFIX: ${{ inputs.doc-prefix }}
+          LOCALREGISTRY: ${{ inputs.localregistry }}
         run: |
-          ${{ inputs.doc-prefix }}julia --project=docs --color=yes <<'EOF'
+          ${DOC_PREFIX}julia --project=docs --color=yes <<'EOF'
           import Pkg
           if VERSION >= v"1.8-"
             Pkg.Registry.add()
           else
             Pkg.Registry.add("General")
           end
-          if !isempty("${{ inputs.localregistry }}")
-            local_repos = split("${{ inputs.localregistry }}", "\n") .|> string
+          localregistry = get(ENV, "LOCALREGISTRY", "")
+          if !isempty(localregistry)
+            local_repos = split(localregistry, "\n") .|> string
             for repo_url in local_repos
               isempty(repo_url) && continue
               Pkg.Registry.add(Pkg.RegistrySpec(; url=repo_url))
@@ -123,7 +134,10 @@ jobs:
       - name: "Build and Deploy Documentation"
         env:
           GITHUB_TOKEN: ${{ inputs.github-token || secrets.GITHUB_TOKEN }}
-        run: ${{ inputs.debug-documenter && 'JULIA_DEBUG="Documenter"' || '' }} ${{ inputs.doc-prefix }}julia --project=docs/ ${{ inputs.coverage && '--code-coverage=user' }} docs/make.jl
+          DOC_PREFIX: ${{ inputs.doc-prefix }}
+          JULIA_DEBUG: ${{ inputs.debug-documenter && 'Documenter' || '' }}
+          COVERAGE_FLAG: ${{ inputs.coverage && '--code-coverage=user' || '' }}
+        run: ${DOC_PREFIX}julia --project=docs/ $COVERAGE_FLAG docs/make.jl
 
       - uses: julia-actions/julia-processcoverage@v1
         if: "${{ inputs.coverage }}"

.github/workflows/FormatCheck.yml

@@ -1,5 +1,17 @@
 name: "Reusable Format Checking Workflow"
 
+# Parse phase of the format-check pipeline. Designed to run on
+# `pull_request:` (no secrets, read-only `GITHUB_TOKEN` for fork PRs)
+# so that PR-controlled content the formatter touches can never reach
+# secrets. The check status this workflow emits is what branch
+# protection should require.
+#
+# Companion: FormatCheckComment.yml runs on `workflow_run:` after this
+# workflow finishes, downloads the artifact uploaded here, and posts /
+# updates the format-suggestion comment. The comment workflow runs in the base
+# repo's trusted context so it can use `FORMATPULLREQUEST_PAT` without
+# exposing it to the parse phase.
+
 on:
   workflow_call:
     inputs:
@@ -25,37 +37,31 @@ on:
         type: boolean
 
 concurrency:
-  # Key on the PR number for `pull_request_target` events; `github.ref` would
-  # resolve to the target branch (`refs/heads/main`) and would put every PR's
-  # format check into the same group, causing each new PR to cancel all other
-  # in-progress format checks across the repo. Fall back to `github.ref` for
-  # non-PR triggers.
+  # Key on the PR number so each PR has its own concurrency group;
+  # falling back to `github.ref` for non-PR triggers.
   group: "${{ inputs.concurrent-jobs && github.run_id || github.event.pull_request.number || github.ref }}:${{ github.workflow }}"
   cancel-in-progress: ${{ !inputs.concurrent-jobs && inputs.cancel-in-progress }}
 
 jobs:
   format-check:
     name: "Check Formatting"
     runs-on: ubuntu-latest
-
     permissions:
       contents: read
-      actions: write
-      pull-requests: write
 
     steps:
-      - name: Check out repository
+      - name: Check out PR head
         uses: actions/checkout@v5
         with:
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0
 
       - name: Setup Julia
         uses: julia-actions/setup-julia@v2
         with:
-          version: '${{ inputs.julia-version }}'
-          arch: 'x64'
+          version: "${{ inputs.julia-version }}"
+          arch: "x64"
 
       - uses: julia-actions/cache@v2
 
@@ -71,76 +77,54 @@ jobs:
 
       - name: Run ITensorFormatter
         id: format
+        env:
+          DIRECTORY: ${{ inputs.directory }}
         run: |
           set +e
-          echo "Formatter will run on: ${{ inputs.directory }}"
-          itpkgfmt ${{ inputs.directory }}
+          echo "Formatter will run on: $DIRECTORY"
+          itpkgfmt "$DIRECTORY"
           FORMAT_EXIT=$?
           if [ $FORMAT_EXIT -ne 0 ]; then
-            echo "exit_code=2" >> $GITHUB_OUTPUT
-            echo "diff=" >> $GITHUB_OUTPUT
-            exit 1
+            : > diff.patch
+            echo "exit_code=2" >> "$GITHUB_OUTPUT"
+            exit 0
           fi
-
-          # Report all changes introduced by the formatter (including newly created files).
-          # `git add -N .` makes newly created (untracked) files appear in `git diff` as additions.
+          # `git add -N .` makes new (untracked) files visible to `git diff`
+          # so the diff captured below covers added files as well.
           git add -N .
-          DIFF=$(git diff)
-          if [ -n "$DIFF" ]; then
-            EXIT_CODE=1
+          git diff > diff.patch
+          if [ -s diff.patch ]; then
+            echo "exit_code=1" >> "$GITHUB_OUTPUT"
           else
-            EXIT_CODE=0
+            echo "exit_code=0" >> "$GITHUB_OUTPUT"
           fi
 
-          echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
-          echo "diff<<EOF" >> $GITHUB_OUTPUT
-          echo "$DIFF" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
-
-      - name: Find comment
-        uses: peter-evans/find-comment@v3
-        id: find-comment
-        with:
-          token: ${{ secrets.FORMATPULLREQUEST_PAT || github.token }}
-          issue-number: ${{ github.event.pull_request.number }}
-          body-includes: '<!-- format-check-summary -->'
-
-      - name: Comment formatting suggestions
-        if: steps.format.outputs.exit_code == 1
-        uses: peter-evans/create-or-update-comment@v4
-        with:
-          token: ${{ secrets.FORMATPULLREQUEST_PAT || github.token }}
-          comment-id: ${{ steps.find-comment.outputs.comment-id }}
-          issue-number: ${{ github.event.pull_request.number }}
-          body: |
-            <!-- format-check-summary -->
-
-            Your PR requires formatting changes to meet the project's style guidelines.
-            Please run the [ITensorFormatter](https://github.com/ITensor/ITensorFormatter.jl) to apply these changes.
-
-            <details>
-            <summary>Click here to view the suggested changes.</summary>
-
-            ~~~diff
-            ${{ steps.format.outputs.diff }}
-            ~~~
-
-            </details>
-          edit-mode: replace
-
-      - name: Update stale comment
-        if: steps.format.outputs.exit_code == 0 && steps.find-comment.outputs.comment-id
-        uses: peter-evans/create-or-update-comment@v4
+      - name: Save metadata for comment workflow
+        if: ${{ always() }}
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          EXIT_CODE: ${{ steps.format.outputs.exit_code }}
+        run: |
+          {
+            echo "pr_number=$PR_NUMBER"
+            echo "pr_head_sha=$PR_HEAD_SHA"
+            echo "exit_code=${EXIT_CODE:-2}"
+          } > metadata.txt
+
+      - name: Upload artifact for comment workflow
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v4
         with:
-          token: ${{ secrets.FORMATPULLREQUEST_PAT || github.token }}
-          comment-id: ${{ steps.find-comment.outputs.comment-id }}
-          issue-number: ${{ github.event.pull_request.number }}
-          body: |
-            <!-- format-check-summary -->
-
-            Your PR no longer requires formatting changes. Thank you for your contribution!
-          edit-mode: replace
+          name: format-check
+          path: |
+            metadata.txt
+            diff.patch
+          if-no-files-found: ignore
 
       - name: Propagate exit code
         run: |
+          # exit 0 -> already formatted; exit 1 -> formatting needed;
+          # exit 2 -> formatter itself errored. The check status reflects
+          # this directly so branch protection can require it.
           exit ${{ steps.format.outputs.exit_code }}