fix: ci - keep the README regeneration bot out of .github/workflows/

.github/workflows/documentation.yml

@@ -221,18 +221,35 @@ jobs:
           # meta.agent.js always rewrites .github/metrics/meta-metrics.json
           # (fresh timestamp), even when no content changed. Only proceed
           # when at least one file other than the metrics file changed.
-          if git status --porcelain -- . ':(exclude).github/metrics/meta-metrics.json' | grep -q .; then
+          #
+          # `.github/workflows/` is excluded for the same reason the create-pull-request
+          # steps below exclude it from `add-paths`: GitHub treats a file directly in
+          # that directory as a workflow definition, so the App token (least privilege,
+          # no `workflows` permission) cannot push a change to it. Excluding it here
+          # keeps the "did anything change?" decision consistent with what the commit
+          # can actually contain, so a push whose only touched file was a workflow does
+          # not report has_changes=true on the strength of a file the push could not
+          # have made.
+          if git status --porcelain -- . ':(exclude).github/metrics/meta-metrics.json' ':(exclude).github/workflows' ':(exclude).github/workflows/**' | grep -q .; then
             echo "has_changes=true" >> "$GITHUB_OUTPUT"
           else
             git checkout -- .github/metrics/meta-metrics.json 2>/dev/null || true
             echo "has_changes=false" >> "$GITHUB_OUTPUT"
-            echo "No content changes (metrics only); skipping README PR."
+            echo "No content changes (metrics only, or .github/workflows/ only); skipping README PR."
           fi
 
       - name: Generate GitHub App token
         # App token (not GITHUB_TOKEN) so the regeneration PR triggers CI and
         # can satisfy develop's required checks. Requires repo/org secrets:
         # BOT_PR_APP_CLIENT_ID and BOT_PR_APP_PRIVATE_KEY.
+        #
+        # `permission-workflows` is intentionally absent. The App stays at least
+        # privilege, and `.github/workflows/` is kept out of the bot's reach
+        # instead: resolve-readme-files.cjs never returns a README under that
+        # directory, and both create-pull-request steps below exclude it from
+        # `add-paths`. Do not add `permission-workflows` to work around a
+        # regeneration failure -- a failure means a workflow file leaked into
+        # the commit, which is the bug, not the missing permission.
         id: app-token
         if: github.event_name != 'pull_request' && steps.readmes.outputs.files != '' && steps.content.outputs.has_changes == 'true'
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
@@ -251,6 +268,23 @@ jobs:
           branch: chore/readme-regeneration
           base: develop
           commit-message: 'chore(docs): regenerate impacted README files'
+          # Defence in depth. resolve-readme-files.cjs already refuses to emit a README
+          # under `.github/workflows/`, but this step is the last gate before the push:
+          # GitHub classifies a file directly in that directory as a workflow -- even a
+          # plain Markdown one -- and rejects the push unless the token carries
+          # `workflows` permission, which this App deliberately does not have.
+          # `add-paths` restricts staging to the repository minus that directory, so
+          # nothing under it can reach the commit even if the resolver regresses or
+          # meta.agent.js rewrites a file some other way.
+          #
+          # The pathspecs are unquoted on purpose. The action passes each comma/newline
+          # separated token straight to git as an argv element (no shell), so quotes
+          # would become part of the pathspec and git fails with
+          # "pathspec '':(exclude)...'' did not match any files". Verified against
+          # peter-evans/create-pull-request@5f6978f.
+          add-paths: |
+            .
+            :(exclude).github/workflows
           title: 'chore(docs): regenerate impacted README files'
           body: |
             Automated README regeneration, Dependabot-style.
@@ -540,12 +574,32 @@ jobs:
 
       - name: Check for changes
         id: changes
-        run: test "$(git status --porcelain | wc -l)" -gt 0 && echo "has_changes=true" >> "$GITHUB_OUTPUT" || echo "has_changes=false" >> "$GITHUB_OUTPUT"
+        # `.github/workflows/` is excluded for the same reason the regenerate job
+        # excludes it: GitHub treats a file directly in that directory as a
+        # workflow and the App token cannot push one. Note this job always
+        # rewrites the tracked .github/reports/mermaid-audit/maintenance-report.md
+        # with a fresh timestamp, so in practice this reads true regardless; the
+        # load-bearing guard against a workflow file reaching the commit is the
+        # `add-paths` on the create-pull-request step below.
+        run: |
+          if git status --porcelain -- . ':(exclude).github/workflows' ':(exclude).github/workflows/**' | grep -q .; then
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Generate GitHub App token
         # App token (not GITHUB_TOKEN) so the maintenance PR triggers CI and
         # can satisfy develop's required checks. Requires repo/org secrets:
         # BOT_PR_APP_CLIENT_ID and BOT_PR_APP_PRIVATE_KEY.
+        #
+        # `permission-workflows` is intentionally absent, for the same reason as in
+        # the regenerate job above: the App stays at least privilege and
+        # `.github/workflows/` is excluded from the commit instead. This job runs
+        # repository-wide fixers (Mermaid, staleness) and inherited the identical
+        # latent flaw, so it carries the same guard. Do not add
+        # `permission-workflows`; a push failure here means a workflow file leaked
+        # into the commit.
         id: app-token
         if: ${{ steps.changes.outputs.has_changes == 'true' && env.DRY_RUN == 'false' }}
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
@@ -564,6 +618,14 @@ jobs:
           branch: chore/docs-maintenance
           base: develop
           commit-message: 'docs: maintenance updates (Mermaid + staleness)'
+          # Same last-gate guard as the regenerate job: keep anything under
+          # `.github/workflows/` out of the commit, because this App token has no
+          # `workflows` permission and GitHub would refuse the push. Unquoted
+          # pathspecs are required -- the action passes each token to git as an
+          # argv element with no shell involved. See the regenerate job above.
+          add-paths: |
+            .
+            :(exclude).github/workflows
           title: 'docs: maintenance updates (Mermaid + staleness)'
           body: |
             Automated documentation maintenance, Dependabot-style.

CHANGELOG.md

@@ -72,6 +72,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Docs Bot Skips Workflows Directory** — Regeneration skips `.github/workflows/`, so its pushes stop failing for want of App token `workflows` permission. (#3687)
 - **Merged Advisory and Spec Defects Corrected** — The advisories newsletter form survives a failed request, tells a blocked address from a fault and counts its rate limit atomically; spec 018 defers auto-approved branch deletion. (#1396)
 - **Docs-Bot Changelog Exemption** — The gate now matches the docs bot in either login shape, so its exemption applies. Bot pull requests with no user-facing content no longer need a changelog entry. (#3603, #3448)
 - **Semantic-Version Release Branches** — Branch checks in CI and the npm script now accept documented release names such as `release/v1.2.3` and `release/v1.2.3-rc1`. ([#3555](https://github.com/lightspeedwp/.github/issues/3555))