Restructure repository as monorepo for PSDocs ecosystem consolidation #407

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)

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

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       # CodeQL security scanning (NEW)
    └── 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

Secret: Add VSCE_PAT for VS Code Marketplace
Environment: Create release environment
Security: Ensure secret scanning enabled

See MONOREPO_MIGRATION.md for complete details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

www.powershellgallery.com
- Triggering command: /usr/bin/pwsh pwsh ./build.ps1 -Package psdocs-azure -Build (dns block)
- Triggering command: /usr/bin/pwsh pwsh -Command Get-PSRepository (dns block)
- Triggering command: /usr/bin/pwsh pwsh ./build.ps1 -Package psdocs-azure -Build ' --output-dir /tmp/playwright-logs --allowed-origins 'localhost;localhost:*;127.0.0.1;127.0.0.1git (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Monorepo Migration: Consolidate PSDocs Repositories

Objective

Restructure the Azure/PSDocs.Azure repository to prepare it as the destination monorepo for consolidating:

Azure/PSDocs.Azure (existing content - stays)
microsoft/PSDocs (PSDocs engine - to be added)
microsoft/PSDocs-vscode (VS Code extension - to be added)

Important Note

This PR creates the monorepo folder structure and CI/CD infrastructure. The actual content from microsoft/PSDocs and microsoft/PSDocs-vscode will need to be added manually using git subtree commands after this PR is merged, as that requires git history manipulation that cannot be done through file changes alone.

Changes Required

1. Create New Directory Structure

Create the following folder structure:

packages/
├── psdocs/
│   └── .gitkeep (placeholder - content will be added via git subtree)
├── psdocs-azure/
│   └── (move existing src/, tests/, templates/, examples/ here)
└── vscode-extension/
    └── .gitkeep (placeholder - content will be added via git subtree)

docs/
├── psdocs/
│   └── .gitkeep
├── psdocs-azure/
│   └── (move existing docs/ content here)
└── vscode/
    └── .gitkeep

build/
└── common.ps1

2. Move Existing PSDocs.Azure Content

Move the following to packages/psdocs-azure/:

src/ → packages/psdocs-azure/src/
tests/ → packages/psdocs-azure/tests/
templates/ → packages/psdocs-azure/templates/
examples/ → packages/psdocs-azure/examples/
PSDocs.Azure.sln → packages/psdocs-azure/PSDocs.Azure.sln
pipeline.build.ps1 → packages/psdocs-azure/pipeline.build.ps1
modules.json → packages/psdocs-azure/modules.json
ps-docs.yaml → packages/psdocs-azure/ps-docs.yaml
ps-project.yaml → packages/psdocs-azure/ps-project.yaml
ps-rule.yaml → packages/psdocs-azure/ps-rule.yaml

Move documentation:

docs/ → docs/psdocs-azure/

3. Create GitHub Actions Workflows

Create .github/workflows/ci.yml:

name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

env:
  DOTNET_VERSION: '8.0.x'
  NODE_VERSION: '20.x'

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      psdocs: ${{ steps.filter.outputs.psdocs }}
      psdocs-azure: ${{ steps.filter.outputs.psdocs-azure }}
      vscode: ${{ steps.filter.outputs.vscode }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            psdocs:
              - 'packages/psdocs/**'
              - 'build/**'
            psdocs-azure:
              - 'packages/psdocs-azure/**'
              - 'packages/psdocs/**'
              - 'build/**'
            vscode:
              - 'packages/vscode-extension/**'

  build-psdocs:
    needs: changes
    if: needs.changes.outputs.psdocs == 'true' || github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}
      
      - name: Setup PowerShell
        shell: pwsh
        run: |
          if (Test-Path packages/psdocs/pipeline.build.ps1) {
            Set-Location packages/psdocs
            ./pipeline.build.ps1 -Build
          } else {
            Write-Host "PSDocs package not yet added - skipping build"
          }
      
      - name: Test PSDocs
        shell: pwsh
        run: |
          if (Test-Path packages/psdocs/pipeline.build.ps1) {
            Set-Location packages/psdocs
            ./pipeline.build.ps1 -Test
          }
      
      - name: Upload PSDocs Module
        if: success() && hashFiles('packages/psdocs/out/modules/PSDocs/') != ''
        uses: actions/upload-artifact@v4
        with:
          name: psdocs-module
          path: packages/psdocs/out/modules/PSDocs/

  build-psdocs-azure:
    needs: [changes, build-psdocs]
    if: |
      always() &&
      (needs.changes.outputs.psdocs-azure == 'true' || github.event_name == 'push') &&
      (needs.build-psdocs.result == 'success' || needs.build-psdocs.result == 'skipped')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}
      
      - name: Download PSDocs Module
        uses: actions/download-artifact@v4
        with:
          name: psdocs-module
          path: packages/psdocs/out/modules/PSDocs/
        continue-on-error: true
      
      - name: Install PSDocs from Gallery (fallback)
        shell: pwsh
        run: |
          if (-not (Test-Path packages/psdocs/out/modules/PSDocs)) {
            Install-Module -Name PSDocs -Scope CurrentUser -Force
          }
      
      - name: Build PSDocs.Azure
        shell: pwsh
        working-directory: packages/psdocs-azure
        run: |
          ./pipeline.build.ps1 -Build
      
      - name: Tes...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

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.

Copilot · 2026-02-03T01:43:49Z

packages/psdocs-azure/pipeline.build.ps1

+    # Copy LICENSE from repo root
+    Copy-Item -Path ../../LICENSE -Destination out/modules/PSDocs.Azure;

-    # Copy third party notices
-    Copy-Item -Path ThirdPartyNotices.txt -Destination out/modules/PSDocs.Azure;
+    # Copy third party notices from repo root
+    Copy-Item -Path ../../ThirdPartyNotices.txt -Destination out/modules/PSDocs.Azure;


Relative paths assume execution from packages/psdocs-azure/ directory, but InvokeBuild tasks may execute from different working directories. Use $PSScriptRoot to construct absolute paths to ensure the files are found regardless of where the script is invoked from.

Copilot · 2026-02-03T01:43:50Z

build.ps1

+
+    # After building psdocs, set up module path for psdocs-azure
+    if ($pkg -eq 'psdocs' -and $Build) {
+        Get-LocalPSDocsModule | Out-Null


The function Get-LocalPSDocsModule modifies $env:PSModulePath but its return value is piped to Out-Null, discarding the boolean result. If the local module isn't found, subsequent builds may fail silently. Consider checking the return value and handling the false case appropriately.

Suggested change

Get-LocalPSDocsModule | Out-Null

$moduleInitialized = Get-LocalPSDocsModule

if (-not $moduleInitialized) {

Write-Error "Failed to locate or initialize the local PSDocs module. Cannot continue building dependent packages."

}

Copilot · 2026-02-03T01:43:50Z

.github/workflows/vscode-ci.yml

+      - name: Publish to VS Marketplace (Pre-release)
+        working-directory: packages/vscode-extension/out/package
+        env:
+          VSCE_PAT: ${{ secrets.VSCE_PAT }}


The PR description mentions adding the VSCE_PAT secret as a post-merge setup task, but the workflow will fail if the secret doesn't exist. Consider adding a step to check for the secret's existence or documenting this prerequisite more prominently in the workflow file itself.

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

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

Uh oh!

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!

Copilot AI Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-        Get-LocalPSDocsModule | Out-Null
+        $moduleInitialized = Get-LocalPSDocsModule
+        if (-not $moduleInitialized) {
+            Write-Error "Failed to locate or initialize the local PSDocs module. Cannot continue building dependent packages."
+        }

Restructure repository as monorepo for PSDocs ecosystem consolidation #407

Are you sure you want to change the base?

Restructure repository as monorepo for PSDocs ecosystem consolidation #407

Uh oh!

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!

How to Review

Skip These (Imported via git subtree)

Changes

Repository Structure

Packages

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

GitHub Copilot Skills

Post-Merge Setup

I tried to connect to the following addresses, but was blocked by firewall rules:

Monorepo Migration: Consolidate PSDocs Repositories

Objective

Important Note

Changes Required

1. Create New Directory Structure

2. Move Existing PSDocs.Azure Content

3. Create GitHub Actions Workflows

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!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Feb 2, 2026 •

edited by vicperdana

Loading