Skip to content

Rewrite branch freeze automation in PowerShell - #14470

Merged
AlesProkop merged 17 commits into
dotnet:mainfrom
AlesProkop:dev/alesprokop/branch-freeze-powershell
Jul 22, 2026
Merged

AlesProkop merged 17 commits into
dotnet:mainfrom
AlesProkop:dev/alesprokop/branch-freeze-powershell

Conversation

@AlesProkop

Copy link
Copy Markdown
Member

Part of #13589

Context

Provides a PowerShell alternative to #14145 for side-by-side review. It preserves the same /freeze and /unfreeze behavior, issue-backed branch state, and required branch-freeze status while removing the Bash, jq, sed, awk, and grep dependencies from the implementation.

Changes Made

  • Replaced handle-command.sh, is-allowed.sh, set-pr-status.sh, and refresh-pr-statuses.sh with PowerShell equivalents that preserve command parsing, authorization exit codes, tracking issue management, workflow outputs, status descriptions, and sequential bulk refresh behavior.
  • Preserved the numbered execution-step comments in handle-command.ps1, set-pr-status.ps1, and refresh-pr-statuses.ps1.
  • Updated branch-freeze-command.yml, branch-freeze-pr-status.yml, and branch-freeze-refresh.yml to invoke the PowerShell scripts on Ubuntu runners.
  • Replaced the Bash mock and test harness with mock-gh.ps1 and run-tests.ps1 using native PowerShell JSON handling.
  • Added coverage for freeze issue creation, already-unfrozen commands, whitespace-only branch arguments, Unicode-safe status truncation, best-effort notification failures, and multi-PR refreshes.
  • Updated branch-freeze-tests.yml to validate PowerShell syntax and run the PowerShell test harness.
  • Removed unsupported queue: max concurrency keys while retaining the supported concurrency groups and cancel-in-progress: false behavior.
  • Updated documentation/branch-freeze.md with the PowerShell test command and implementation details.

Testing

  • Ran the original Bash test harness from Freeze Functionality #14145: 13 passed, 0 failed.
  • Ran pwsh .github/branch-freeze/tests/run-tests.ps1 on Windows: 32 passed, 0 failed.
  • Ran the same PowerShell tests with PowerShell 7.6.3 on Linux: 32 passed, 0 failed.
  • Ran PSScriptAnalyzer over .github/branch-freeze: 0 errors, 0 warnings.
  • Ran actionlint over all four branch-freeze workflows: 0 errors.
  • Did not run the MSBuild product test suite because no engine or product code changed.

Notes

  • This is an alternative implementation of Freeze Functionality #14145 for comparison; the two PRs are not intended to merge together.
  • Repository administrators must still complete the rollout steps documented in documentation/branch-freeze.md before making branch-freeze a required status.

AlesProkop and others added 14 commits June 24, 2026 09:19
Posts the required �ranch-freeze commit status on a PR head commit, red
(state=failure, with reason) while the PR base branch is frozen and green
(state=success) otherwise. Freeze state is read from open issues labeled
�ranch-freeze whose body carries a whole-line marker <!-- branch-freeze:<branch> -->.

Part of automating branch-blocking (dotnet#13589).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extract the freeze-status core into a shared post-freeze-status.sh (single
source of truth) wrapped by the composite action, and add the
branch-freeze-status.yml workflow:

* pull_request_target [opened, synchronize, reopened, edited] stamps the
  triggering PR (edited re-evaluates on base retarget).
* workflow_dispatch / workflow_call bulk-stamp open PRs (rollout seed and
  freeze/unfreeze fan-out).

Validated with shellcheck + actionlint and a mock-gh/real-jq test suite.
Part of automating branch-blocking (dotnet#13589).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add branch-freeze-command.yml: an issue_comment slash command, restricted to
the @<org>/kitten team via an org-scoped GitHub App token (members:read) used
ONLY for the membership check; all repo mutations use GITHUB_TOKEN.

freeze-command.sh parses /freeze [--branch <name>] <reason> and
/unfreeze [--branch <name>], upserts/closes the branch-freeze tracking issue
(reconciling duplicates), and emits branch/changed outputs. A fanout job then
re-stamps open PRs via the reusable branch-freeze-status workflow, sharing a
per-branch concurrency group with the single-PR stamps so a freeze fan-out can
never be overwritten by a concurrent stale stamp.

Also factor the bulk loop into the shared stamp-open-prs.sh.

Validated with shellcheck + actionlint and a stateful-mock-gh test suite.
Part of automating branch-blocking (dotnet#13589).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add documentation/branch-freeze.md (committer usage + how it works + one-time
admin rollout/rollback runbook) and link it from the docs index.

Part of automating branch-blocking (dotnet#13589).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Match documentation to the ASCII \Frozen: <reason>\ status description.
- Scope statuses:write / pull-requests:read to the fanout job only (the command
  job needs just contents:read + issues:write).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Authorization for /freeze and /unfreeze now uses .github/branch-freeze-allowlist.txt (via is-allowed.sh) instead of an org-scoped GitHub App membership check, avoiding the app-approval burden. The tracking issue records who froze the branch and the failing status now reads 'Frozen by @<login>: <reason>'. Adds security-focused shell unit tests (mock gh) and a CI workflow to run them.
Check out the repository default branch so pull_request_target runs for release branches can load the trusted local action.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 2ea53811-dacd-4bf3-a37f-fa0ef6fcbc7c
Retain pending freeze commands and status writes so later events cannot silently replace earlier serialized work.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 2ea53811-dacd-4bf3-a37f-fa0ef6fcbc7c
Warn instead of aborting when a confirmation comment fails so successful state changes still trigger status fanout.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 2ea53811-dacd-4bf3-a37f-fa0ef6fcbc7c
Split single-PR evaluation from bulk refresh, move the shell scripts into a dedicated branch-freeze directory, and document each responsibility.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7eae7093-a91c-432d-9c5b-9720d1d5a2d4
Keep the moved executable scripts marked executable after the directory refactor.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7eae7093-a91c-432d-9c5b-9720d1d5a2d4
Replace the Bash runtime and test scripts with PowerShell equivalents while preserving the issue-backed freeze state, required status behavior, workflow outputs, and readable step comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7eae7093-a91c-432d-9c5b-9720d1d5a2d4
Use one permanent issue per branch and centralize the PowerShell implementation around shared lifecycle helpers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7eae7093-a91c-432d-9c5b-9720d1d5a2d4

@jankratochvilcz jankratochvilcz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Muuuch better!!! Focused on the code for this round, left some comments.

Image

Comment thread .github/branch-freeze/BranchFreeze.psm1 Resolved
Comment thread .github/branch-freeze/BranchFreeze.psm1 Resolved
Comment thread .github/branch-freeze/BranchFreeze.psm1 Resolved
Comment thread .github/branch-freeze/BranchFreeze.psm1 Resolved
Comment thread documentation/branch-freeze.md Resolved

@jankratochvilcz jankratochvilcz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left one small comment to introduce a folder structure to keep things tidy. Otherwise thnigs are looking 💯!!

@AlesProkop
AlesProkop marked this pull request as ready for review July 22, 2026 12:31
Copilot AI review requested due to automatic review settings July 22, 2026 12:31
@AlesProkop
AlesProkop requested a review from a team as a code owner July 22, 2026 12:31

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR rewrites the branch-freeze (merge-freeze) GitHub automation from Bash to PowerShell, preserving the /freeze and /unfreeze behavior, issue-backed freeze state, and required branch-freeze status while removing dependencies on common Unix utilities.

Changes:

  • Adds a PowerShell implementation of the branch-freeze command handling, status stamping, and bulk refresh logic (plus supporting modules/clients).
  • Adds a PowerShell-based unit test harness with a mocked gh CLI, and a workflow to validate PowerShell syntax + run tests on PRs touching branch-freeze files.
  • Documents the feature and its rollout steps, and links the doc from the documentation index.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
documentation/README.md Adds documentation index link for branch-freeze.
documentation/branch-freeze.md New doc describing usage, implementation, admin setup, and rollback.
.github/workflows/branch-freeze-tests.yml New CI workflow to validate PowerShell syntax and run branch-freeze unit tests.
.github/workflows/branch-freeze-refresh.yml New reusable/manual workflow to bulk refresh branch-freeze statuses via PowerShell.
.github/workflows/branch-freeze-pr-status.yml New workflow to set branch-freeze status on PR events using trusted base context + PowerShell.
.github/workflows/branch-freeze-command.yml New workflow to process /freeze and /unfreeze comments, authorize via allowlist, and trigger refresh.
.github/branch-freeze/tests/run-tests.ps1 PowerShell unit test runner covering auth, parsing/composition, command handling, and refresh behavior.
.github/branch-freeze/tests/mock-gh.ps1 PowerShell mock of gh used by the unit tests.
.github/branch-freeze/set-pr-status.ps1 PowerShell script to publish the required branch-freeze commit status for a single PR SHA/base branch.
.github/branch-freeze/refresh-pr-statuses.ps1 PowerShell script to enumerate open PRs and sequentially stamp branch-freeze status.
.github/branch-freeze/is-allowed.ps1 PowerShell allowlist authorization script with deny-by-default semantics.
.github/branch-freeze/handle-command.ps1 PowerShell handler for /freeze and /unfreeze that updates tracking issue state and writes workflow outputs.
.github/branch-freeze/GitHubStatusChecksClient.psm1 Module wrapper for publishing commit statuses via gh api.
.github/branch-freeze/GitHubRepositoryClient.psm1 Module helpers for repo name resolution and branch existence validation.
.github/branch-freeze/GitHubPullRequestsClient.psm1 Module helper for enumerating open PRs (used by bulk refresh).
.github/branch-freeze/GitHubIssuesClient.psm1 Module wrapper for label/issue/comment/reaction operations via gh.
.github/branch-freeze/GitHubCli.psm1 Central gh invocation wrapper with retry/exit-code handling.
.github/branch-freeze/deny-command.ps1 Script for replying/reacting to unauthorized command attempts.
.github/branch-freeze/BranchFreezeCommentParser.psm1 Pure parsing logic for slash commands and issue bodies.
.github/branch-freeze/BranchFreezeCommentComposer.psm1 Pure composition logic for issue bodies, replies, audit comments, and status description truncation.
.github/branch-freeze/BranchFreeze.psm1 Domain module implementing tracking-issue lifecycle rules (open/close/state lookup).
.github/branch-freeze-allowlist.txt New checked-in allowlist controlling who can run /freeze and /unfreeze.
.gitattributes Ensures LF line endings for branch-freeze .ps1 scripts to support Linux runner execution.

@AlesProkop
AlesProkop merged commit 317c30b into dotnet:main Jul 22, 2026
11 checks passed
AlesProkop added a commit that referenced this pull request Jul 23, 2026
### Context

Follow-up to #14470. The `/freeze` /unfreeze` command workflow only
requested `issues: write`, but it reacts to and replies on the
*triggering comment*. When a command is issued from a **pull request**
comment, GitHub requires `pull-requests: write` for those operations, so
the best-effort acknowledgement (👍 reaction + confirmation reply) failed
with `HTTP 403`. The freeze/unfreeze state change itself always
succeeded; only the acknowledgement on PR comments was affected.
Confirmed live during rollout testing (a `/freeze` from a PR comment
applied the freeze and stamped the required status red, but posted no
ack).

### Changes Made

- Added `pull-requests: write` to the `command` job permissions in
`branch-freeze-command.yml` so reactions/replies succeed when the
command originates from a PR comment. This also covers the
`deny-command` step (same job).
- Changed `Add-Reaction` in `handle-command.ps1` to log a `::warning::`
instead of silently swallowing a failed reaction, so any future
permission gap is diagnosable.
- Tightened the adjacent permissions comment (removed the now-inaccurate
`pull-requests: read` note; `statuses: write` remains scoped to the
refresh job).

### Testing

- Ran `pwsh .github/branch-freeze/tests/run-tests.ps1`: **73 passed, 0
failed**.
- Validated PowerShell parser over `.github/branch-freeze/**`
(`*.ps1`/`*.psm1`): no errors.
- Parsed `branch-freeze-command.yml` with `powershell-yaml`: valid;
command-job permissions now `{contents: read, issues: write,
pull-requests: write}`.

### Notes

- Behavior when commanded from a regular **issue** comment was already
correct and is unchanged.
- The `deny-command` path already logged reaction failures via
`Write-Warning` and needs no change beyond the shared permission.

Copilot-Session: 7eae7093-a91c-432d-9c5b-9720d1d5a2d4
AlesProkop added a commit that referenced this pull request Jul 29, 2026
Automated flaky-test quarantine (2026-07-27).

---

## Quarantine: `SingleBuild_CoordinatorCapsMaxNodeCount`

**Flaky-test key** (automated de-duplication — do not edit):
```text
flaky-test-id: Microsoft.Build.Coordinator.UnitTests.CoordinatorIntegration_Tests.SingleBuild_CoordinatorCapsMaxNodeCount
```

Tracked by #14516

- **Action**: quarantine (6a) — added
`[ActiveIssue("https://github.com/dotnet/msbuild/issues/14516")]`
- **File**:
`src/MSBuild.Coordinator.UnitTests/CoordinatorIntegration_Tests.cs`
- **Distinct sources**: 3 (3 PRs: #13609, #14240, #14470; 0 rolling
builds)
- **Legs**: CoreOnLinux, CoreOnWindows, FullOnWindows Release
- **TFMs**: net10.0, net11.0, net472
- **Error hashes**: 3 distinct (`4039adb7`, `55b6331b`, `ba217936`)
- **First seen**: 2026-07-17 | **Last seen**: 2026-07-23
- [Sample
build](https://dev.azure.com/dnceng-public/public/_build/results?buildId=1523327)

---

## Also tracked this run (new issues filed; quarantine eligible next
run)

-
`Microsoft.Build.BuildCheck.UnitTests.EndToEndTests.TFMinNonSdkCheckTest`
(3 rolling builds, 4 error hashes)
-
`Microsoft.Build.Engine.UnitTests.MSBuildServer_Tests.ServerSpawnAndReuseAreLoggedToBuildLog`
(3 rolling builds, 3 error hashes)
- `Microsoft.Build.UnitTests.CommunicationUtilitiesTests.GetEnvVars` (3
rolling builds, 2 error hashes)

---

## Skipped (possible regression — human triage needed)

The following tests showed a **single stable error hash** failing across
the same set of 4 rolling builds with no PR sources, which may indicate
a regression rather than a flake:

- `Microsoft.Build.UnitTests.CodeTaskFactoryTests.*` (7 tests, hash
`2f59b830`, builds 1506834/1514373/1517682/1527742)
- `Microsoft.Build.UnitTests.CodeTaskFactoryTests.EmbedsGenerated*` (2
tests, hash `d888cdeb`, same builds)

These were **not quarantined** to avoid masking a real bug. Human
investigation recommended.




> [!WARNING]
> <details>
> <summary>Firewall blocked 2 domains</summary>
>
> The following domains were blocked by the firewall during workflow
execution:
>
> - `awmgmcpg`
> - `southcentralus0.in.applicationinsights.azure.com`
>> To allow these domains, add them to the `network.allowed` list in
your workflow frontmatter:
>
> ```yaml
> network:
>   allowed:
>     - defaults
>     - "awmgmcpg"
>     - "southcentralus0.in.applicationinsights.azure.com"
> ```
>
> See [Network
Configuration](https://github.github.com/gh-aw/reference/network/) for
more information.
>
> </details>


> Generated by [Flaky Test
Triage](https://github.com/dotnet/msbuild/actions/runs/30267259222) ·
sonnet46 · 153.8 AIC · ⌖ 6.72 AIC · ⊞ 14.7K ·
[◷](https://github.com/search?q=repo%3Adotnet%2Fmsbuild+%22gh-aw-workflow-id%3A+flaky-test-detector.agent%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: Flaky Test Triage, engine: copilot,
version: 1.0.70, model: claude-sonnet-4.6, id: 30267259222, workflow_id:
flaky-test-detector.agent, run:
https://github.com/dotnet/msbuild/actions/runs/30267259222 -->

<!-- gh-aw-workflow-id: flaky-test-detector.agent -->
<!-- gh-aw-workflow-call-id: dotnet/msbuild/flaky-test-detector.agent
-->

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Aleš Prokop <ales.prokop.dev@gmail.com>
AlesProkop added a commit that referenced this pull request Aug 12, 2026
Reverts #14495 and #14470.

No other changes.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 42691a11-7401-40fe-b781-87654fed03fa
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants