Restructure repository as monorepo for PSDocs ecosystem consolidation by Copilot · Pull Request #407 · Azure/PSDocs.Azure

Copilot · 2026-02-02T06:52:06Z

This PR transforms PSDocs.Azure into a monorepo consolidating the complete PSDocs ecosystem:

PSDocs (core engine from microsoft/PSDocs)
PSDocs.Azure (existing content, restructured)
VS Code Extension (from microsoft/PSDocs-vscode)

⚠️ Why Checks Are "Waiting for status"

The startup_failure on new workflows (CI, VS Code Extension CI) is a known GitHub Actions security restriction: the Azure org prevents new workflow files introduced in a PR from running on pull_request events until they exist on the default branch. This resolves automatically after merge.

The stuck "Expected" checks (Build, Test (linux-musl-x64-pwsh), Analyze with PSRule, etc.) come from deleted workflows (build.yaml, analyze.yaml) that can no longer report status.

🔑 Admin Action Required to Merge

A repo admin needs to either:

Remove/update required status checks in branch protection rules (remove refs to deleted workflow jobs)
Admin override merge — bypass check requirements for this structural change

Fix Commits (6 commits)

Round 1: PR Review Fixes

`d26add8` — fix: address PR #407 review issues and build failure

Fixes CI build failure and addresses all 3 Copilot review comments:

Fix	File	Details
🔴 Removed legacy workflows	`build.yaml`, `analyze.yaml`	Superseded by `ci.yml` and `codeql.yml`; `build.yaml` caused the CI failure
🟡 Reliable path resolution	`pipeline.build.ps1`	Use `$PSScriptRoot`-based paths instead of relative `../../`
🟡 Error handling	`build.ps1`	Check `Get-LocalPSDocsModule` return value instead of `Out-Null`
🟡 Secret guard	`vscode-ci.yml`	Guard publish step with `VSCE_PAT` existence check
📝 Migration docs	`MONOREPO_MIGRATION.md`	Added workflow migration table

`4bba770` — fix: repair release workflows and docs output path

Fix	File	Details
🔴 InvokeBuild setup	`release-psdocs.yml`, `release-psdocs-azure.yml`	Added missing `Install-Module InvokeBuild` step
🔴 Build invocation	`release-psdocs.yml`, `release-psdocs-azure.yml`	Fixed: `./pipeline.build.ps1 -Build` → `Invoke-Build Build -File ./pipeline.build.ps1`
🟡 Docs output path	`docs.yaml`	Updated `outputPath` to `docs/psdocs-azure/templates/`

Round 2: Restore Missing CI Checks

`63b3159` — fix: restore missing CI status checks from deleted workflows

Added back all checks that the deleted build.yaml and analyze.yaml provided:

ci.yml — Cross-platform test matrix:

Test (linux-x64-pwsh), Test (linux-musl-x64-pwsh), Test (win-x64-pwsh), Test (win-x64-powershell), Test (osx-x64-pwsh)
Downloads built module artifact → runs Invoke-Build TestModule

codeql.yml (renamed to "Analyze") — Security & code analysis:

Analyze with PSRule — PSRule OSS rules analysis
Analyze with DevSkim — DevSkim security scanner
Analyze with CodeQL — C# CodeQL analysis (was missing; only had JS/TS)
CodeQL — JS/TS CodeQL for VS Code extension (kept)

Round 3: Workflow Compatibility Fixes

`e64234a` — fix: pin all action references to SHA hashes

All action refs pinned to commit SHAs matching versions used on main (Azure org policy).

`63e00ff` — fix: replace dorny/paths-filter with native git diff

Replaced third-party dorny/paths-filter with bash git diff to comply with org action restrictions.

`3f189d7` — fix: add explicit permissions to all workflows

Added permissions: {} at workflow level and contents: read/write at job level for all new workflows.

How to Review

368 files, ~33k lines — but most are imported via git subtree. Focus on these areas:

Priority	What to Review	Files
🔴 High	Build scripts & CI workflows	`build.ps1`, `.github/workflows/*.yml`
🔴 High	Path fixes for monorepo	`packages/psdocs-azure/pipeline.build.ps1`
🟡 Medium	Copilot skills	`.github/skills/*.md`
🟢 Low	Subtree imports (trusted external code)	`packages/psdocs/`, `packages/vscode-extension/`

Skip These (Imported via git subtree)

packages/psdocs/** - Imported from microsoft/PSDocs
packages/vscode-extension/** (except workflow changes) - Imported from microsoft/PSDocs-vscode

Changes

Repository Structure

packages/
├── psdocs/              # PSDocs engine (added via git subtree)
├── psdocs-azure/        # Azure IaC documentation generator
└── vscode-extension/    # VS Code extension (added via git subtree)
.github/
├── skills/              # GitHub Copilot skills (4 skills)
└── workflows/
    ├── ci.yml           # Main CI with path-based filtering
    ├── vscode-ci.yml    # VS Code CI (NEW - migrated from Azure DevOps)
    ├── codeql.yml       # Security & code analysis (NEW - replaces analyze.yaml)
    └── release-*.yml    # Release workflows

VS Code Extension CI/CD (Migrated from Azure DevOps)

Multi-channel build (preview/stable)
Cross-platform testing (macOS, Windows PS5.1/7.x, Ubuntu)
Preview auto-publish on main merge
CodeQL security scanning
Deleted: .azure-pipelines/ folder

GitHub Copilot Skills

Skill	Model	Purpose
`monorepo-code-review`	opus4.5	Code review for monorepo
`powershell-csharp-expert`	sonnet4.5	PowerShell/C# development
`devops-build`	sonnet4.5	CI/CD and build system
`documentation`	sonnet4.5	Documentation maintenance

Post-Merge Setup

Priority	Task
🔴 Required	Add `VSCE_PAT` secret (VS Marketplace PAT)
🔴 Required	Add `PSGALLERY_API_KEY` secret (PowerShell Gallery API key)
🔴 Required	Create `release` GitHub environment
🟡 Recommended	Update branch protection to reference new CI check names
🟡 Recommended	Verify all workflows pass on main after merge

See MONOREPO_MIGRATION.md for complete details.

This pull request was created from Copilot chat.

Co-authored-by: vicperdana <7114832+vicperdana@users.noreply.github.com>

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Add 4 specialized Copilot skills to .github/skills/: - monorepo-code-review.md (opus4.5): Comprehensive code review focused on monorepo consolidation and build verification - powershell-csharp-expert.md (sonnet4.5): PowerShell module and C# .NET backend development - devops-build.md (sonnet4.5): GitHub Actions workflows and InvokeBuild scripts - documentation.md (sonnet4.5): Markdown docs and MkDocs Each skill supports nested sub-agents for parallel exploration, build verification, and focused analysis tasks.

- build.ps1: Use Invoke-Build with -Task and -File parameters - ci.yml: Use 'Invoke-Build Build/Test -File ./pipeline.build.ps1' - pipeline.build.ps1: Fix paths to LICENSE, ThirdPartyNotices.txt, and docs (now at repo root level, not package level) Build verified locally - all packages compile successfully.

git-subtree-dir: packages/psdocs git-subtree-split: 7bab9feddf8a3b8ee6f2d2d3dc90df6553ee5f1b

git-subtree-dir: packages/vscode-extension git-subtree-split: 672ac07f9e60465a93b0850f22baf6e08ebf8283

…ions - Add vscode-ci.yml: Multi-channel build (preview/stable), cross-platform testing (macOS, Windows PS5.1/7.x, Ubuntu), preview auto-publish on main - Add codeql.yml: CodeQL security scanning for TypeScript/JavaScript - Update release-vscode.yml: Use InvokeBuild for stable releases - Update package.json: Change repo URLs to Azure/PSDocs.Azure - Delete .azure-pipelines/: Remove Azure DevOps pipeline (fully migrated) - Update MONOREPO_MIGRATION.md: Remove post-merge steps (subtrees added), document new workflows

- Add compile step before tests (tests need compiled output) - Use xvfb-run wrapper for Linux tests (proper display server) - Add VSIX file validation (fail fast if missing) - Fix channel variable check in pipeline.build.ps1 (was checking literal string 'Channel' instead of $Channel variable)

vicperdana · 2026-02-02T12:28:19Z

Just for visibility for now @BernieWhite fyi.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Instructs code review agents to: - Focus on build scripts, workflows, and psdocs-azure package - Treat packages/psdocs and packages/vscode-extension as vendored (git subtree imports) - skip unless critical security issue

Copilot

Pull request overview

Copilot reviewed 178 out of 369 changed files in this pull request and generated 3 comments.

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

packages/psdocs-azure/pipeline.build.ps1

build.ps1

.github/workflows/vscode-ci.yml

- Remove legacy build.yaml and analyze.yaml workflows (superseded by ci.yml and codeql.yml); fixes 'Missing default script' CI build error - Use $PSScriptRoot-based paths in pipeline.build.ps1 CopyModule task for reliable path resolution regardless of working directory - Add error handling for Get-LocalPSDocsModule return value in build.ps1 - Guard vscode-ci.yml publish step with VSCE_PAT secret existence check - Document workflow migration in MONOREPO_MIGRATION.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add InvokeBuild module installation to release-psdocs.yml and release-psdocs-azure.yml (was missing, causing 'Invoke-Build not recognized' errors) - Fix build invocation in release workflows: use Invoke-Build Build -File ./pipeline.build.ps1 instead of ./pipeline.build.ps1 -Build (pipeline.build.ps1 is an InvokeBuild script, not directly callable) - Update docs.yaml outputPath from docs/templates/ to docs/psdocs-azure/templates/ to match monorepo directory structure Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vicperdana

@BernieWhite could you take a look before this is merged? Thanks

- Add cross-platform test matrix to ci.yml matching old build.yaml: linux-x64, linux-musl-x64, win-x64 (pwsh + powershell), osx-x64 - Rename codeql.yml workflow to 'Analyze' and add: - PSRule analysis (Analyze with PSRule) from old analyze.yaml - DevSkim security scanning (Analyze with DevSkim) from old analyze.yaml - C# CodeQL analysis (Analyze with CodeQL) from old analyze.yaml - Keep existing JS/TS CodeQL for VS Code extension - Add pipeline-deps.ps1 and PSRule results upload to build job - Match old check names for branch protection rule compatibility Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@v4

Azure org policy requires SHA-pinned action references. Replace all tag-based refs (@v4, @V3, etc.) with full commit SHA pins matching the versions used in existing workflows on main. This fixes the startup_failure on CI and VS Code Extension CI workflows that have been failing since the PR was created. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace third-party dorny/paths-filter action with a bash-based git diff approach. The Azure org likely restricts allowed actions to first-party (actions/*, github/*, microsoft/*) only, which would explain the persistent startup_failure on CI workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Azure org requires explicit permissions declarations. Add 'permissions: {}' at workflow level and 'contents: read/write' at job level for all new workflows, matching the pattern used by existing workflows on main (build.yaml, analyze.yaml, etc.). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Initial plan

76d8138

Copilot AI assigned Copilot and vicperdana Feb 2, 2026

Copilot started work on behalf of vicperdana February 2, 2026 06:52 View session

Copilot AI and others added 3 commits February 2, 2026 06:56

feat: create monorepo structure with packages and docs directories

86cd740

Co-authored-by: vicperdana <7114832+vicperdana@users.noreply.github.com>

feat: add build scripts and update workflows for monorepo

102e1fd

Co-authored-by: vicperdana <7114832+vicperdana@users.noreply.github.com>

docs: add monorepo migration guide

b959ba6

Co-authored-by: vicperdana <7114832+vicperdana@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Prepare monorepo structure for PSDocs repositories~~ Restructure repository as monorepo for PSDocs ecosystem consolidation Feb 2, 2026

Copilot AI requested a review from vicperdana February 2, 2026 07:02

Copilot finished work on behalf of vicperdana February 2, 2026 07:02

vicperdana requested a review from Copilot February 2, 2026 08:32

Copilot AI reviewed Feb 2, 2026

View reviewed changes

vicperdana requested a review from Copilot February 2, 2026 10:48

vicperdana added 10 commits February 2, 2026 22:39

chore: remove psdocs placeholder for subtree merge

4ddcbf9

Squashed 'packages/psdocs/' content from commit 7bab9fe

4e1ee61

git-subtree-dir: packages/psdocs git-subtree-split: 7bab9feddf8a3b8ee6f2d2d3dc90df6553ee5f1b

feat: add PSDocs engine from microsoft/PSDocs

6dd3be1

chore: remove vscode-extension placeholder for subtree merge

014c9f3

Squashed 'packages/vscode-extension/' content from commit 672ac07

044d079

git-subtree-dir: packages/vscode-extension git-subtree-split: 672ac07f9e60465a93b0850f22baf6e08ebf8283

feat: add VS Code extension from microsoft/PSDocs-vscode

d6fa2fd

vicperdana requested a review from BernieWhite February 2, 2026 12:27

Copilot AI reviewed Feb 2, 2026

View reviewed changes

docs: add Copilot instructions for code review guidance

e6a81b3

Instructs code review agents to: - Focus on build scripts, workflows, and psdocs-azure package - Treat packages/psdocs and packages/vscode-extension as vendored (git subtree imports) - skip unless critical security issue

vicperdana requested a review from Copilot February 3, 2026 01:42

Copilot AI reviewed Feb 3, 2026

View reviewed changes

packages/psdocs-azure/pipeline.build.ps1 Outdated Show resolved Hide resolved

build.ps1 Outdated Show resolved Hide resolved

.github/workflows/vscode-ci.yml Show resolved Hide resolved

vicperdana marked this pull request as ready for review April 7, 2026 02:57

vicperdana requested a review from a team as a code owner April 7, 2026 02:57

vicperdana marked this pull request as draft April 7, 2026 02:59

vicperdana marked this pull request as ready for review April 7, 2026 03:16

vicperdana approved these changes Apr 7, 2026

View reviewed changes

vicperdana and others added 4 commits April 7, 2026 19:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure repository as monorepo for PSDocs ecosystem consolidation#407

Restructure repository as monorepo for PSDocs ecosystem consolidation#407
Copilot wants to merge 21 commits intomainfrom
copilot/monorepo-migration-psdocs

Copilot AI commented Feb 2, 2026 •

edited by vicperdana

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

vicperdana commented Feb 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vicperdana left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Feb 2, 2026 • edited by vicperdana Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Why Checks Are "Waiting for status"

🔑 Admin Action Required to Merge

Fix Commits (6 commits)

Round 1: PR Review Fixes

d26add8 — fix: address PR #407 review issues and build failure

4bba770 — fix: repair release workflows and docs output path

Round 2: Restore Missing CI Checks

63b3159 — fix: restore missing CI status checks from deleted workflows

Round 3: Workflow Compatibility Fixes

e64234a — fix: pin all action references to SHA hashes

63e00ff — fix: replace dorny/paths-filter with native git diff

3f189d7 — fix: add explicit permissions to all workflows

How to Review

Skip These (Imported via git subtree)

Changes

Repository Structure

VS Code Extension CI/CD (Migrated from Azure DevOps)

GitHub Copilot Skills

Post-Merge Setup

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

vicperdana commented Feb 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vicperdana left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 2, 2026 •

edited by vicperdana

Loading

`d26add8` — fix: address PR #407 review issues and build failure

`4bba770` — fix: repair release workflows and docs output path

`63b3159` — fix: restore missing CI status checks from deleted workflows

`e64234a` — fix: pin all action references to SHA hashes

`63e00ff` — fix: replace dorny/paths-filter with native git diff

`3f189d7` — fix: add explicit permissions to all workflows