Idempotent Windows Workstation Onboarding with PowerShell and winget

Expected Outcome

A workstation can be brought to a defined baseline with approved winget packages and settings, rerun without reinstalling everything, and produce a report showing installed, already-compliant, failed, and reboot-required items.

Assumptions

• Supported Windows edition with winget/App Installer available or an explicitly documented enterprise package source

• Administrator rights only for settings/packages that require them

• A version-controlled list of package IDs and desired settings

• An execution policy/code-signing approach defined by the organization; the lab does not change ExecutionPolicy just to run interactively

Bill of Materials

• Windows 10/11 workstation

• PowerShell 5.1 or later

• Text editor (e.g., Visual Studio Code, Notepad++)

• List of required software packages

Build Steps

1. Define desired state with real package identifiers

   Use winget package IDs plus desired version/channel where needed. Separate machine settings from package installs and document which actions require elevation or reboot.

2. Detect before changing

   For each package/setting, test whether the desired state already exists. Return AlreadyCompliant when true; do not reinstall or rewrite values on every run.

3. Install packages non-interactively with bounded behavior

   Invoke winget with explicit IDs and agreement/silent options appropriate to the package. Capture exit code/stdout/stderr and classify reboot-required separately from failure.

4. Apply settings through explicit functions

   Create small functions for each approved Windows setting. Each function has Test and Set behavior, logs the prior state, and skips unsupported OS editions rather than failing the whole onboarding run.

5. Produce a structured onboarding report

   Emit one object per package/setting with Name, DesiredState, PreviousState, Result, ExitCode, RebootRequired, and Detail, then export the same objects to a local evidence file.

6. Prove idempotency

   Run the toolkit twice on the same lab workstation. The second run should report mostly AlreadyCompliant and must not create duplicate software/settings or unnecessary reboot requests.

Validation

• Every software item uses a real package ID/source rather than C:\Path\To\Installer placeholders

• The script does not change ExecutionPolicy as a prerequisite

• A successful first run produces the intended package/settings baseline

• A second run is idempotent and reports compliant state

• Failures and reboot-required results are distinct

• The final report is usable under the same account/context planned for deployment

Troubleshooting

• Package not found: verify source and exact ID before falling back to another installer mechanism

• Interactive works but deployment does not: compare execution identity, winget availability/source context, proxy, and elevation

• Do not hide installer exit codes behind a generic success/failure message

Cleanup or Rollback

• Remove only packages/settings installed solely for the lab using their supported uninstall/backout method

• Keep the desired-state file and report under version control

Next Improvements

• Document the onboarding process for future reference.

• Consider adding logging functionality to the script for troubleshooting.

• Expand the toolkit to include additional configurations or software as needed.