ci: harden GitHub Actions token and input handling

[thetechgy]

📑 Description

Hardens GitHub Actions token and input handling while preserving active automation behavior:

• Reduces the automatic GITHUB_TOKEN in update-public-suffix-list to contents: read.
• Uses the read-only automatic token for checkout in Maester Bot automation, then mints App tokens immediately before pull request creation with only contents: write and pull-requests: write.
• Passes module version, website version, and release-tag values to shell steps through step-local environment variables instead of direct expression interpolation.
• Disables persisted checkout credentials in read-only jobs, while retaining checkout authentication in release/versioning jobs that later push through it.
• Removes the obsolete update-tag-documentation workflow and its sole-purpose build/Update-TagsDocumentation.ps1 generator. GitHub records 116 runs from January 19 through July 25, including 73 on non-main branches. Those runs performed checkout with contents: write, installed Pester, discovered tests, and wrote website/docs/tests/tags/readme.md; however, after the generator moved to that path, the commit step continued checking website/docs/tags.md, logged No changes to commit, and discarded the generated change. Repository history contains no matching chore: update tags documentation bot commit. Since May, website/scripts/generate-test-docs.mjs has owned the current linked tag index and is enforced by the website checks and prebuild, so removing the legacy workflow and script eliminates nonfunctional automation without removing active documentation behavior.
• Updates the cpina/github-action-push-to-another-repository pin to the immutable v1.7.3 SHA and aligns the smoke-test checkout pin with v7.0.1.

The persisted checkout credentials in publish jobs remain an accepted residual because stefanzweifel/git-auto-commit-action requires them for its later push. Existing active triggers, jobs, matrices, artifacts, branches, tags, inputs, release fallback behavior, and generated outputs remain unchanged.

Supporting guidance:

• GitHub Actions secure use reference
• actions/create-github-app-token permissions
• peter-evans/create-pull-request token guidance
• actions/checkout credential persistence
• stefanzweifel/git-auto-commit-action checkout requirement

✅ Checks

• My pull request adheres to the code style of this project.
• My code requires changes to the documentation. The repository-restructure proposal referenced the removed legacy script.
• I have updated the documentation as required. The stale proposal reference was removed; generated documentation is unchanged.
• The build and unit tests pass after running /powershell/tests/pester.ps1 locally.

Local validation completed:

• Every remaining workflow file parsed successfully as YAML.
• Structural comparisons confirmed that only the intended token boundaries, environment-variable handling, checkout settings, action pins, obsolete workflow and script removals, and associated proposal cleanup changed.
• A repository-wide reference check confirmed that no Update-TagsDocumentation references remain.
• The official upstream tags resolve to the pinned cpina v1.7.3 and checkout v7.0.1 SHAs.
• npm --prefix website run check-test-docs passed and checked 407 generated test-documentation pages.
• git diff --check upstream/main passed.
• The Pester wrapper was attempted. After installing the same project dependencies used by CI and isolating the run to the CI-pinned Pester 5.7.1, it completed the general-test phase and then stopped producing output in Common.Tests.ps1 for more than 15 minutes. The local run was stopped and is not reported as passing; the required Ubuntu, Windows, and macOS build-validation jobs are the authoritative full-suite result.

Current PR checks for commit e951cbc3:

• Passed: CodeQL Actions and JavaScript/TypeScript analysis, PowerShell analysis, PSScriptAnalyzer, Codacy, command-reference generation, and command-reference drift detection.
• The website build reached npm run check-test-docs and failed only because the pre-existing generated contributor snapshot website/src/data/contributors.json is stale.
• The required Ubuntu, Windows, and macOS build-validation jobs each ran 10,224 tests and reported the same nine failures: the Global Secure Access functions added in Add 9 Global Secure Access checks (MT.1187–MT.1195) [Preview] #1992 do not satisfy the repository-wide Write-Verbose policy test. This PR does not change those functions, and an unrelated PR run immediately before this one failed on the same checks, so no unrelated GSA implementation was added to this focused workflow-hardening change.
• The PR remains draft until the upstream validation failures are resolved and all required checks pass.

ℹ️ Additional Information

No repository variables, secrets, environments, generated command documentation, generated test documentation, module output, or runtime dependencies are added or changed. No prior issue is required for this focused maintenance change.

Summary by CodeRabbit

• Security

  • Improved workflow credential handling by preventing checkout credentials from persisting.
  • Reduced default workflow permissions and limited access to required operations.
  • Updated token generation to request explicit permissions only when needed.

• Maintenance

  • Improved version and release value handling across publishing workflows.
  • Updated an action revision used when publishing tests.

• Removed

  • Removed the automated tag documentation generation workflow and associated script.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e4c97d00-7c04-49aa-b742-096623eb5c8c

📥 Commits

Reviewing files that changed from the base of the PR and between e951cbc and f9086e9.

📒 Files selected for processing (4)

• .github/workflows/build-website.yaml
• .github/workflows/publish-module-manualversionupdate.yaml
• .github/workflows/publish-module.yaml
• .github/workflows/publish-versioned-docs.yml

💤 Files with no reviewable changes (1)

• .github/workflows/build-website.yaml

🚧 Files skipped from review as they are similar to previous changes (3)

• .github/workflows/publish-versioned-docs.yml
• .github/workflows/publish-module-manualversionupdate.yaml
• .github/workflows/publish-module.yaml

---

📝 Walkthrough

Walkthrough

The pull request hardens GitHub Actions checkout and token handling, passes release values through environment variables, updates a publishing action revision, and removes the tag documentation generation workflow and script with a corresponding proposal reference cleanup.

Changes

Workflow maintenance

Layer / File(s)	Summary
Checkout and token flow updates .github/workflows/build-docs.yaml, .github/workflows/build-website.yaml, .github/workflows/update-*.yaml, .github/workflows/codeql.yml, .github/workflows/dependency-review.yaml, .github/workflows/opengrep.yml, .github/workflows/build-maester-report-template.yaml	Checkout steps disable credential persistence. Documentation and update workflows generate GitHub App tokens after repository updates, with explicit permissions where required.
Release version environment propagation .github/workflows/publish-module*.yaml, .github/workflows/publish-tests.yaml, .github/workflows/publish-versioned-docs.yml	Module, release-tag, and website-version values are passed through step environment variables to PowerShell and Node commands; the tests workflow pins a newer publishing action.
Tag documentation cleanup .github/workflows/update-tag-documentation.yaml, build/Update-TagsDocumentation.ps1, docs/proposals/repo-restructure.md	The tag documentation generation workflow and script are removed, and the restructuring proposal no longer references the deleted script.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• maester365/maester#1873: Updates related GitHub Actions checkout steps to disable credential persistence.
• maester365/maester#1901: Also changes an actions/checkout step to use persist-credentials: false.
• maester365/maester#1914: Updates the same repository restructuring proposal around the removed tag documentation script.

Suggested labels: github_actions, automation, enhancement

Suggested reviewers: merill

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the PR’s main focus on hardening GitHub Actions token and input handling.
Description check	✅ Passed	The description follows the template well, with a clear summary, checks, and additional information; the issue link is simply left blank.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[Copilot]

Pull request overview

This PR hardens GitHub Actions token usage and shell input handling by reducing default GITHUB_TOKEN privileges, limiting credential persistence on checkouts, and deferring higher-privilege GitHub App token minting until just before PR creation. It also removes legacy, nonfunctional tag-documentation automation.

Changes:

• Reduce default workflow/job token privileges and disable persisted checkout credentials in read-only jobs.
• Mint GitHub App tokens only immediately before PR creation, with narrowly scoped contents: write / pull-requests: write.
• Avoid direct ${{ }} interpolation in shell commands by passing values via step-local environment variables; remove obsolete tag doc workflow/script and update action pins.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/proposals/repo-restructure.md	Removes obsolete proposal reference to the deleted tag-doc generator.
build/Update-TagsDocumentation.ps1	Removes legacy tag documentation generator script.
.github/workflows/update-tag-documentation.yml	Removes legacy workflow that attempted to generate/commit tag docs.
.github/workflows/update-role-definitions.yaml	Uses read-only checkout token; mints App token only for PR creation; disables persisted creds.
.github/workflows/update-public-suffix-list.yaml	Reduces default job token to contents: read; mints App token only for PR creation; disables persisted creds.
.github/workflows/update-module-docs.yaml	Uses read-only checkout token; mints App token only for PR creation; disables persisted creds.
.github/workflows/build-docs.yaml	Uses read-only checkout token; mints App token only for PR creation; disables persisted creds.
.github/workflows/publish-versioned-docs.yml	Passes input version to Node via step env var (safer shell argument handling).
.github/workflows/publish-tests.yaml	Disables persisted checkout creds; passes release tag via env vars; updates cpina action pin.
.github/workflows/publish-module.yaml	Passes module version via env vars into PowerShell/Node steps.
.github/workflows/publish-module-preview.yaml	Passes module version via env vars into PowerShell/Node steps.
.github/workflows/publish-module-manualversionupdate.yaml	Passes module version via env vars into PowerShell/Node steps.
.github/workflows/opengrep.yml	Disables persisted checkout creds in scan job.
.github/workflows/maester-action-smoke-test.yaml	Aligns checkout pin to actions/checkout v7.0.1 SHA.
.github/workflows/dependency-review.yaml	Disables persisted checkout creds for dependency review job.
.github/workflows/codeql.yml	Disables persisted checkout creds (but currently introduces invalid YAML indentation in steps).
.github/workflows/build-website.yaml	Disables persisted checkout creds across website build jobs.
.github/workflows/build-maester-report-template.yaml	Disables persisted checkout creds in report-template build job.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[SamErde]

I love the intent and the goal of this PR! The one thing I want to check: the newer test auto-documentation workflow doesn't completely replace what the tag documentation workflow does (as far as I have seen). Let's see if we can find a way to get feature parity before the tag documentation is removed.

As an aside, I think the last website reorganization resulted in some valuable pages being lost from the navigation structure and I'd like to see some of those recovered as well.

[thetechgy]

I love the intent and the goal of this PR! The one thing I want to check: the newer test auto-documentation workflow doesn't completely replace what the tag documentation workflow does (as far as I have seen). Let's see if we can find a way to get feature parity before the tag documentation is removed.

As an aside, I think the last website reorganization resulted in some valuable pages being lost from the navigation structure and I'd like to see some of those recovered as well.

I was under the impression that website/scripts/generate-test-docs.mjs replaced the .github/workflows/update-tag-documentation.yml workflow + build/Update-TagsDocumentation.ps1 script. Additionally, looking at the run history, that workflow doesn't appear to have led to a commit in the past year.

I could be wrong on both points, but that's how it seemed to me. It would be good if someone else could verify or disprove :)

[SamErde]

Additionally, looking at the run history, that workflow doesn't appear to have led to a commit in the past year.

I didn't think that workflow was even a year old?

[thetechgy]

Additionally, looking at the run history, that workflow doesn't appear to have led to a commit in the past year.

I didn't think that workflow was even a year old?

You're right - it was introduced in commit d2ddee1 in December 2025.

What I meant was that based on the run history since it was implemented, the workflow doesn't appear to have produced a commit. I phrased that poorly.