If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Azure/azure-powershell shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 41+ active contributors
• Distributed ownership (top contributor 28% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Azure/azure-powershell repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Azure/azure-powershell.

What it runs against: a local clone of Azure/azure-powershell — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Azure/azure-powershell | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Azure/azure-powershell. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Azure/azure-powershell.git
#   cd azure-powershell
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Azure/azure-powershell and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Azure/azure-powershell(\\.git)?\\b" \\
  && ok "origin remote is Azure/azure-powershell" \\
  || miss "origin remote is not Azure/azure-powershell (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "build.proj" \\
  && ok "build.proj" \\
  || miss "missing critical file: build.proj"
test -f ".azure-pipelines/azure-powershell-ci.yml" \\
  && ok ".azure-pipelines/azure-powershell-ci.yml" \\
  || miss "missing critical file: .azure-pipelines/azure-powershell-ci.yml"
test -f "Repo.props" \\
  && ok "Repo.props" \\
  || miss "missing critical file: Repo.props"
test -f ".azure-pipelines/PipelineSteps/BatchGeneration/batch-generate-modules.ps1" \\
  && ok ".azure-pipelines/PipelineSteps/BatchGeneration/batch-generate-modules.ps1" \\
  || miss "missing critical file: .azure-pipelines/PipelineSteps/BatchGeneration/batch-generate-modules.ps1"
test -f ".azure-pipelines/util/build-steps.yml" \\
  && ok ".azure-pipelines/util/build-steps.yml" \\
  || miss "missing critical file: .azure-pipelines/util/build-steps.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Azure/azure-powershell"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Azure PowerShell is the official PowerShell module ecosystem for managing Microsoft Azure resources. It provides cmdlets that wrap Azure REST APIs, allowing developers and operators to deploy, configure, and manage Azure infrastructure, services, and resources through PowerShell scripts. The repo is a massive monorepo generating 200+ service-specific modules (Az.Compute, Az.Storage, etc.) that roll up into two distribution channels: Az (stable) and AzPreview (with preview features). Monorepo structure: /src/ contains service-specific modules (Az.Compute/, Az.Storage/, etc.) each with cmdlet implementations in C#. .azure-pipelines/ orchestrates generation (batch-generation.yml → BatchGeneration/*.ps1 scripts analyze, generate, build, and test modules in parallel). .devcontainer/ provides Dockerfile + post-create.ps1 for consistent dev environments. Code generation likely happens via AutoRest or similar—each module wraps an Azure API contract.

Cloud operators and Azure developers who automate infrastructure-as-code workflows, manage Azure resources via scripts, or run administrative tasks. Contributors are Microsoft engineers and community members maintaining service cmdlets across 200+ Azure service modules. DevOps engineers using Azure Cloud Shell rely heavily on this being pre-installed.

Highly mature and production-critical. The repo is actively maintained by Microsoft with a large C# codebase (1.6GB), extensive CI/CD pipelines (.azure-pipelines/ with batch generation, live tests, and release workflows), and official distribution through PowerShell Gallery and Microsoft Artifact Registry. This is the primary supported way to manage Azure resources from PowerShell.

Low technical risk for end-users (it's Microsoft-maintained), but high complexity risk for contributors due to 200+ interdependent modules, intricate code generation pipelines (batch-generation.yml), and large monorepo surface area. Breaking changes require careful rollout. Onboarding friction is significant—understanding the batch generation system, module structure, and test infrastructure takes time.

Active batch generation pipeline runs across multiple modules. The repo uses Azure Pipelines for continuous integration (azure-powershell-ci.yml), live testing (live-test.yml), and release testing (release-test.yml). Recent work includes pipeline maintenance (sync-MSdoc.yml, sync-aliases.yml, sync-squad-mapping.yml suggest active documentation and internal mapping updates). No specific new features visible in file list, but infrastructure automation is sophisticated and constantly refined.

Clone the repository:

git clone https://github.com/Azure/azure-powershell.git
cd azure-powershell

Open the .devcontainer in VS Code (Remote - Containers extension) or run locally. Review .devcontainer/post-create.ps1 for setup. Install dependencies (likely requires .NET SDK and PowerShell 7+). See .azure-pipelines/ for build pipeline structure.

Daily commands: No single 'run' command—this is a library, not an app. To build a specific module: use the batch generation pipeline scripts in .azure-pipelines/PipelineSteps/BatchGeneration/ (batch-generate-modules.ps1, build-modules.ps1). To test locally: run test-modules.ps1. Individual modules can be built via dotnet build in their src/*/` directories. Publish to PowerShell Gallery via release pipeline (release-test.yml).

• build.proj — Root MSBuild project file orchestrating the entire build process for all Azure PowerShell modules; essential entry point for compilation and packaging.
• .azure-pipelines/azure-powershell-ci.yml — Primary CI/CD pipeline configuration that runs on every commit; defines build, test, and validation stages for the entire codebase.
• Repo.props — Shared MSBuild properties file containing common build settings and version information used across all module projects.
• .azure-pipelines/PipelineSteps/BatchGeneration/batch-generate-modules.ps1 — Core PowerShell script that orchestrates batch generation of Azure module cmdlets from OpenAPI specifications; critical for code generation pipeline.
• .azure-pipelines/util/build-steps.yml — Reusable Azure Pipelines template defining standard build step configuration used across multiple pipeline definitions.
• .ci-config.json — Configuration file specifying which modules are included in CI/CD runs, module dependencies, and build targets.
• Directory.Build.targets — MSBuild targets file providing common build logic and targets inherited by all module projects in the solution.

Add a New Azure PowerShell Module

1. Create module project structure following existing module layout in src directory (src/*/[ModuleName].sln (reference from existing modules))
2. Add module configuration to CI configuration with dependencies and build order (.ci-config.json)
3. Update shared build properties if module requires new SDK versions or targets (Repo.props)
4. Configure batch generation if module is auto-generated from OpenAPI specs (.azure-pipelines/PipelineSteps/BatchGeneration/batch-generate-modules.ps1)
5. Add module to rollup package definition and update version in shared properties (Repo.props)

Modify CI/CD Pipeline Behavior

1. Edit main CI pipeline configuration to add new stages or change triggers (.azure-pipelines/azure-powershell-ci.yml)
2. Update or create reusable pipeline step templates referenced by main pipeline (.azure-pipelines/util/build-steps.yml or .azure-pipelines/util/test-steps.yml)
3. Modify batch generation logic if changes affect module generation workflow (.azure-pipelines/PipelineSteps/BatchGeneration/batch-generate-modules.ps1)
4. Update notification templates if changing failure or success reporting (.azure-pipelines/PipelineSteps/BatchGeneration/notify-failed-job.ps1)

Update Build Properties and Targets

1. Add shared properties like SDK versions, target frameworks, or common flags (Repo.props)
2. Add MSBuild targets that all projects should inherit (Directory.Build.targets)
3. Update root build orchestration if adding new build phases or output types (build.proj)

• PowerShell — Native scripting language for Azure administration; all cmdlets and automation scripts are PowerShell-based for direct Azure resource management.
• MSBuild — Standard .NET build system; enables consistent compilation, property inheritance, and target orchestration across 50+ interdependent module projects.
• Azure Pipelines — Microsoft-native CI/CD platform with deep Azure integration; provides secure credential management, artifact hosting, and multi-stage build orchestration.
• OpenAPI/Swagger Specifications — Source of truth for Azure API definitions; enables automatic code generation of cmdlets maintaining parity with Azure REST APIs.

• Batch code generation pipeline vs. hand-written modules

  • Why: Reduces manual maintenance burden and ensures consistency across 50+ modules; enables rapid API coverage expansion.
  • Consequence: Generated code may be less optimized for specific use cases; harder to customize individual module behavior without post-generation modifications.

• Centralized Repo.props and Directory.Build.targets for all modules

  • Why: Ensures consistent versioning, SDK targets, and build behavior across the entire monorepo; reduces configuration duplication.
  • Consequence: Changes to shared properties affect all modules simultaneously; requires careful testing and versioning discipline to avoid breaking changes.

• Multi-stage pipeline with dependency analysis and batch builds

  • Why: Optimizes build time by parallelizing independent module builds while respecting dependency chains; reduces full build time significantly.
  • Consequence: Complex pipeline logic adds maintenance burden; dependency cycles or misconfiguration can cause cascading build failures.

• Not a runtime framework: Azure PowerShell does not execute code, only provides cmdlets for users to call Azure

1. Batch generation complexity: The PowerShell-based code generation (BatchGeneration/*.ps1) is non-trivial. Understanding how batch-generate-modules.ps1 orchestrates parallel builds and dependency resolution requires deep reading. 2. Module interdependencies: Many modules depend on common modules (e.g., Az.Accounts). Breaking changes propagate across the graph—the pipeline carefully manages this via dependency analysis. 3. Code generation artifacts: Cmdlet code may be auto-generated from Azure API specs via AutoRest or similar—directly editing generated files is dangerous. Find the generation source. 4. Azure Pipelines secrets: Live tests (live-test.yml) and releases likely require Azure Pipelines secrets (KeyVault integration via get-keyvault-secret-steps.yml)—local testing without proper setup will fail auth. 5. PowerShell versioning: Module targets both PowerShell 7+ and Windows PowerShell 5.1—test matrix is broad; code must be compatible across both.

• Code Generation from OpenAPI/Swagger Specs — Azure SDK cmdlets are largely auto-generated from service API contracts using AutoRest—contributors must understand where generated code lives and how to extend or override it.
• Monorepo with Parallel CI/CD Orchestration — 200+ modules in one repo demand sophisticated batching and parallelization in the pipeline (batch-generation.yml, BatchGeneration/*.ps1)—understanding task orchestration and dependency graphs is key to making changes.
• PowerShell Cmdlet Architecture (Command, Parameter, Output) — Azure PowerShell cmdlets follow strict patterns (CmdletBase, ParameterSets, OutputTypes, pipeline binding)—contributors must understand how C# cmdlet classes map to PowerShell commands.
• Azure Service Principal and RBAC Authentication — Live tests and release pipelines use service principals with Azure RBAC—understanding how Az.Accounts module provides authentication context is critical for testing and release workflows.
• PowerShell Pester Testing Framework — Az modules use Pester for cmdlet behavior testing—contributors writing or maintaining tests need Pester patterns (Describe, It, Mock, Assert).
• Azure SDK Dependency Management and Versioning — Each Az module depends on specific versions of Azure SDK NuGet packages; batch generation performs dependency resolution to avoid conflicts—mismanaging versions breaks the entire release.
• Cross-Platform Compatibility (Windows PowerShell 5.1 vs PowerShell 7+) — Az cmdlets must run on both legacy Windows PowerShell 5.1 (.NET Framework) and modern PowerShell 7+ (.NET Core/.NET 5+)—code must avoid APIs not available in both runtimes.

• Azure/azure-cli — Official Azure CLI (Python/Go equivalent to PowerShell Az)—manages same resources, different language ecosystem.
• Azure/azure-sdk-for-python — Official Python SDK for Azure services—the underlying REST API abstractions that Az cmdlets wrap.
• Azure/azure-sdk-for-net — Official .NET SDK for Azure—directly used by Az cmdlets' C# implementation layer.
• Azure/autorest — Code generator that likely powers cmdlet stub generation from Azure API specifications.
• PowerShell/PowerShell — The PowerShell runtime itself—Az modules run on top of this; understanding PSCore 7+ is essential for contributors.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create comprehensive README for .azure-pipelines/PipelineSteps/BatchGeneration scripts

The BatchGeneration folder contains 10+ critical PowerShell scripts (batch-generate-modules.ps1, build-modules.ps1, test-modules.ps1, etc.) but lacks documentation on their purpose, dependencies, and execution order. New contributors cannot understand the batch generation workflow. A detailed README would explain the pipeline orchestration, parameter requirements, and error handling patterns used across these scripts.

• [ ] Create .azure-pipelines/PipelineSteps/BatchGeneration/README.md documenting each script's purpose
• [ ] Document the execution flow and dependencies between scripts (e.g., prepare.ps1 → batch-generate-modules.ps1 → build-modules.ps1 → test-modules.ps1)
• [ ] Add examples showing how to run scripts locally and interpret their outputs
• [ ] Document the util.psm1 module and common functions exported by it
• [ ] Include troubleshooting section for common failures in batch generation pipelines

Add unit tests for .azure-pipelines/PipelineSteps/BatchGeneration/util.psm1

The util.psm1 module is imported and used by multiple pipeline scripts (batch-generate-modules.ps1, build-modules.ps1, test-modules.ps1, analyze-modules.ps1) but there are no visible unit tests. This shared utility module is critical infrastructure that lacks test coverage. Adding Pester tests would catch regressions early and document expected behavior of common functions.

• [ ] Create .azure-pipelines/PipelineSteps/BatchGeneration/util.tests.ps1 using Pester framework
• [ ] Identify all exported functions in util.psm1 and write test cases for each
• [ ] Include tests for error handling and edge cases (empty inputs, malformed data, missing dependencies)
• [ ] Add tests to verify integration with module filtering and analysis logic
• [ ] Configure CI to run Pester tests on changes to util.psm1

Enhance .azure-pipelines/README.md with pipeline architecture documentation and troubleshooting guide

The .azure-pipelines/README.md exists but the file structure shows 12+ YAML pipeline files (batch-generation.yml, live-test.yml, powershell-core.yml, windows-powershell.yml, etc.) with unclear relationships. New contributors cannot understand which pipelines run when, their dependencies, or how to debug failures. A comprehensive architecture guide with a pipeline dependency diagram would significantly reduce onboarding time.

• [ ] Document each pipeline file's purpose (batch-generation.yml for batch module generation, live-test.yml for integration tests, etc.)
• [ ] Create a visual dependency diagram showing how pipelines trigger each other (batch-generation.yml → test-modules, etc.)
• [ ] Document the util/ folder structure and when each .yml template is used
• [ ] Add troubleshooting section explaining common pipeline failures and how to interpret logs from azure-pipelines UI
• [ ] Include instructions for locally testing pipeline steps using PowerShell (similar to GitHub Actions act tool)

• Add missing cmdlet documentation to a low-traffic module (e.g., check SyncDocsConfig.json for modules not yet synced to Microsoft Learn)—PR to update SyncDocsConfig.json and/or add missing .md files in the docs.: High-impact but low-risk: improves discoverability, doesn't touch core logic.
• Extend test coverage for a service module (e.g., Az.Network or Az.Storage) by adding new Pester tests in src/[ServiceName]/[ServiceName].Test/ covering edge cases or error conditions shown in cmdlet help.: Concrete and isolated—doesn't require understanding the entire generation pipeline, but strengthens the test suite.
• Improve error messages or help text in a specific cmdlet (e.g., add better parameter validation or examples to Get-AzVM help) by editing the C# cmdlet class in src/Compute/Compute/Cmdlets/VirtualMachine/ and running local tests.: Builds familiarity with cmdlet structure and the help generation system without large refactoring.

The Azure PowerShell repository demonstrates a reasonable security posture with documented security reporting processes (SECURITY.md) and infrastructure-as-code practices. However, there are moderate concerns around PowerShell script security in CI/CD pipelines, potential credential exposure in build logs, and container image security. The primary risks involve injection attacks in pipeline scripts, secret leakage through logging, and supply chain vulnerabilities. No critical vulnerabilities were identified based on the provided file

• Medium · PowerShell Scripts in CI/CD Pipeline Without Explicit Security Controls — .azure-pipelines/PipelineSteps/BatchGeneration/. Multiple PowerShell scripts in .azure-pipelines/PipelineSteps/BatchGeneration directory execute with elevated privileges in CI/CD context. Scripts like batch-generate-modules.ps1, build-modules.ps1, and test-modules.ps1 could be vulnerable to injection attacks if they process untrusted input from pull requests or external sources without proper sanitization. Fix: Implement strict input validation and sanitization in all PowerShell scripts. Use parameter validation attributes, avoid using Invoke-Expression with user input, and enforce script signing policies in the CI/CD pipeline.
• Medium · Potential Credential Exposure in Azure Pipeline Configuration — .azure-pipelines/util/get-keyvault-secret-steps.yml, .azure-pipelines/util/get-github-pat-steps.yml. Multiple Azure Pipeline YAML files (.azure-pipelines/*.yml) use pattern names like 'get-keyvault-secret-steps.yml' and 'get-github-pat-steps.yml', suggesting retrieval of secrets. If these secrets are logged or printed in pipeline output without proper masking, they could be exposed in build logs accessible to unauthorized users. Fix: Ensure all Azure Pipeline tasks that retrieve secrets use Azure's built-in secret masking. Configure pipeline logging to exclude sensitive variables and audit log retention policies. Use managed identities instead of PATs where possible.
• Medium · Docker Images Without Explicit Security Scanning Configuration — docker/Dockerfile-alpine-3.23, docker/Dockerfile-azurelinux-3.0, docker/Dockerfile-debian-12, docker/Dockerfile-ubuntu-24.04. Multiple Dockerfile variants in the docker/ directory (alpine, azurelinux, debian, ubuntu) are present without visible security scanning or vulnerability assessment configuration in the repository root. These images used for build environments should be regularly scanned for vulnerabilities. Fix: Integrate automated container image scanning into the CI/CD pipeline using tools like Azure Container Registry scanning or Trivy. Regularly update base image versions and implement a container security policy. Document the scanning results.
• Low · Dependency Management Configuration Present — NuGet.Config. NuGet.Config file is present in the repository root, which manages NuGet package sources and credentials. While this is necessary, it requires careful management to prevent dependency confusion attacks or man-in-the-middle attacks if using external feeds. Fix: Ensure NuGet.Config uses HTTPS for all package sources, validates package integrity, and implements clear separation between internal and external feeds. Regularly audit package sources and consider using a private NuGet feed for internal dependencies.
• Low · GitHub Workflow Scripts Require Review Controls — .github/workflows/, .github/workflows/script/PrLabeled.ps1. GitHub Actions workflows (.github/workflows/*.yml) and supporting scripts (.github/workflows/script/PrLabeled.ps1) execute automated actions on repository events. Without proper approval gates, these could potentially be exploited through workflow manipulation. Fix: Implement mandatory pull request reviews for workflow file changes, use GitHub's environment protection rules with required approvals, and audit all workflow permissions. Use GitHub's 'pull_request_target' carefully with explicit checkout controls.
• Low · Devcontainer Configuration Exposes Development Environment — .devcontainer/Dockerfile, .devcontainer/devcontainer.json, .devcontainer/post-create.ps1. Devcontainer files (.devcontainer/Dockerfile, .devcontainer/devcontainer.json, .devcontainer/post-create.ps1) define the development environment. If not properly configured, they could include unnecessary tools or permissions that increase attack surface. Fix: Follow principle of least privilege in devcontainer configuration. Use minimal base images, avoid running as root, disable unnecessary services, and regularly update dependencies. Scan the container for vulnerabilities before committing changes.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.