Skip to main content

Development

This page documents development workflows for the NinjaOne PowerShell module.

Quick Start​

pwsh -File .\DevOps\Build\bootstrap.ps1
pwsh -File .\DevOps\Build\build.ps1 -TaskNames build
pwsh -File .\DevOps\Quality\test.ps1

Contributing​

There are many ways to contribute to the project, including:

  • Submitting bug reports and feature requests.
  • Opening pull requests with bug fixes and new features.
  • Improving documentation and examples (note that most docs are generated from comment-based help, so doc improvements often come with code changes).
  • Reviewing and providing feedback on open pull requests.
  • Sponsoring development on GitHub Sponsors.

Development Process​

Improvements should be submitted via pull requests against the develop branch. This allows for review and testing before merging into main for release. The project uses a CI workflow to run tests and build on pull requests, and a separate workflow to handle releases when changes are merged into main and tagged.

PRs against main which are not from our develop branch will be closed without review, so please ensure you are targeting the correct branch. If you are unsure about the process or have questions, feel free to ask in the Homotechsual Discord or the NinjaOne Discord.

Repo Layout​

  • DevOps/Build - build orchestration scripts and build config.
  • DevOps/Quality - test and static analysis scripts.
  • DevOps/Help - comment-based help generation and orchestration.
  • Source - module source.
  • Tests - Pester tests.
  • docs/NinjaOne - generated commandlet docs output.

Bootstrap Environment​

Bootstrap installs required modules, prioritizes bundled modules, and configures git hooks.

pwsh -File .\DevOps\Build\bootstrap.ps1

If you need to force reinstalling dependencies:

pwsh -File .\DevOps\Build\bootstrap.ps1 -Force

Build​

The build script supports multiple tasks:

  • clean
  • build
  • updateManifest
  • publish
  • publishDocs
  • updateHelp
  • generateShortNamesMapping
  • push

Build only:

pwsh -File .\DevOps\Build\build.ps1 -TaskNames build

Default full build (clean, build, update manifest, publish help/docs, push):

pwsh -File .\DevOps\Build\build.ps1

Tests​

Tests run with Pester 5.x. By default, the test script also runs ScriptAnalyzer.

pwsh -File .\DevOps\Quality\test.ps1

Skip ScriptAnalyzer during tests:

pwsh -File .\DevOps\Quality\test.ps1 -SkipScriptAnalyzer

PSScriptAnalyzer​

Run the standalone analyzer pass (uses PSScriptAnalyzerSettings.psd1):

pwsh -File .\DevOps\Quality\run-pssa.ps1

The analyzer excludes CustomRules, output, Modules, and test-rules.ps1.

Help Generation​

The help orchestration script runs in phases:

  • Generate
  • ApplyPublic
  • Verify
  • ApplyPrivate
  • All

Run all phases:

pwsh -File .\DevOps\Help\Orchestrate-HelpGeneration.ps1 -Phase All

Full Request Example Generation​

The full request example generator injects a dedicated help example for POST/PUT/PATCH cmdlets that accept request bodies. It reads the OpenAPI YAML (downloaded by default) and inserts a help block between the explicit markers shown below. Existing examples remain untouched.

It requires a ConvertFrom-Yaml implementation (install either powershell-yaml or Yayaml).

# FULL REQUEST EXAMPLE (AUTO-GENERATED) - BEGIN
# FULL REQUEST EXAMPLE (AUTO-GENERATED) - END

Default run (downloads the OpenAPI YAML from the EU tenant):

pwsh -File .\DevOps\Help\Generate-FullRequestExamples.ps1

Point at a local OpenAPI YAML file:

pwsh -File .\DevOps\Help\Generate-FullRequestExamples.ps1 -YamlPath C:\path\to\NinjaRMM-API-v2.yaml

Target a single endpoint path:

pwsh -File .\DevOps\Help\Generate-FullRequestExamples.ps1 -EndpointPath /v2/user/end-users

Target a specific cmdlet:

pwsh -File .\DevOps\Help\Generate-FullRequestExamples.ps1 -CommandName New-NinjaOneEndUser

What it does:

  • Downloads or loads the OpenAPI YAML and parses request body schemas.
  • Builds a minimal example object from the schema (first option for oneOf/anyOf/allOf).
  • Updates only the marked example block in comment-based help.
  • Inserts the example before the .OUTPUTS section if no block exists.

Common parameters:

  • -BaseUrl defaults to https://eu.ninjarmm.com.
  • -SourcePath defaults to Source\Public.
  • -EndpointPath and -CommandName filter the scope.

Docs Generation​

Regenerate the short name map and update docs output:

pwsh -File .\DevOps\Build\build.ps1 -TaskNames generateShortNamesMapping,updateHelp,publishDocs

Release and Versioning​

  • The build script accepts -SemVer to set a specific version during build.
  • Publishing and release packaging are handled via CI and build tasks.

Documentation​

Comprehensive guides for development workflows:

PR Checklist​

  • Run bootstrap.ps1 after pulling new dependencies.
  • Run build.ps1 -TaskNames build before opening a PR.
  • Run test.ps1 (or test.ps1 -SkipScriptAnalyzer if PSSA is already run).
  • Run run-pssa.ps1 to validate style and quality rules.
  • Update comment-based help and docs if you touched public functions.
  • Confirm CHANGELOG.md is updated when appropriate.
  • Review Styling & Conventions for code standards.
  • Review Quality Gates & Code Standards for parameter documentation.

Need Help?​

See the Troubleshooting Guide for solutions to common issues.

Last updated on by Mikey O'Toole