How startautomating/psdevops works
Project type and purpose
• PSDevOps is an open-source PowerShell module designed to simplify DevOps automation.
• It provides pipeline-aware cmdlets to wrap the Azure DevOps and GitHub REST APIs, custom formatting/type extensions, generation of CI/CD pipelines (Azure DevOps & GitHub), and publishing to the PowerShell Gallery.
File structure
• Top level: core module manifest (PSDevOps.psd1/psm1), helper scripts (PSDevOps.*.ps1), tests, CI definitions (azure-pipelines.yml, action.yml), documentation, and assets.
• Directories:
• Ado – pipeline “parts” (jobs, stages, steps, triggers) for Azure DevOps pipeline generation
• GitHub – analogous parts for GitHub Actions/Workflows
• Formatting – custom .format.ps1 scripts to control PowerShell table/list views
• Types – Extended Type System PS1/XML files to decorate returned objects
• Functions – functional implementation split by area: AzureDevOps, Git, GitHub, plus shared utilities (Convert-BuildStep, Expand-BuildStep, etc.)
• Parts – building-block scripts/metadata for pipeline-as-code
• docs – CLI reference and change logs
• CI/CD:
• .github/workflows and Ado/Workflows house pipelines for testing, linting (PSScriptAnalyzer, ScriptCop), cross-platform Pester tests, and publishing artifacts.
Extract architecture insights from README
• Core layers:
a. REST wrappers (Invoke-ADORestAPI, Invoke-GitHubRESTAPI)
b. Cmdlet layer (Get-ADO*, New-ADOPipeline, Connect-GitHub, New-GitHubAction, etc.)
c. Formatting & type extensions to augment API output
d. Pipeline-as-code engine (New-ADOPipeline, New-GitHubWorkflow) using “parts”
• Extensibility: modules can drop their own ADO/GitHub parts under an \ADO or \GitHub folder to override default parts.
Main components and interactions
a. User/PowerShell Host
• Imports PSDevOps module
• Invokes cmdlets
b. PSDevOps Module
• Function Layer (Functions folder)
• REST Adapter Layer (Invoke-ADORestAPI & Invoke-GitHubRESTAPI)
• Formatting/Types Layer (Formatting & Types folders)
• Pipeline-As-Code Engine (Parts, Ado, GitHub folders)
c. External Services
• Azure DevOps REST API
• GitHub REST API
• PowerShell Gallery (publishing module)
d. CI/CD Infrastructure
• Azure Pipelines (azure-pipelines.yml, Ado workflows)
• GitHub Actions (action.yml, .github/workflows)
e. Documentation Site
• docs folder → site generator (e.g., Jekyll) → GitHub Pages or similar
• Cmdlets → REST Adapter → External APIs
• Cmdlets → Formatting/Types → PowerShell Output
• New-ADOPipeline/New-GitHubWorkflow → Pipeline “parts” → CI definitions
• CI definitions → run linters/tests → publish to PowerShell Gallery
• docs folder → site generator → published documentation
Architectural patterns & design principles
• Layered architecture: separation of cmdlet logic, REST transport, formatting, and code-gen engine.
• Plugin/override mechanism: module–specific \ADO or \GitHub parts override core.
• Pipeline-aware functions: heavy use of PowerShell object pipeline & ShouldProcess pattern.
• CI/CD as code: all pipelines defined declaratively in the repo.
Don’t overthink—capture all logical components
• Break PSDevOps into as many meaningful pieces as possible: host, module layers, external APIs, CI, docs.