Windows ISO Builder

Automated pipeline for building and optimizing Windows ISO images via GitHub Actions.

Combines UUP dump ISO assembly with Tiny11 optimization into a single workflow.

---

🔄 Pipeline

UUP dump API → Download UUP files → Build ISO → Finalize ISO → Upload raw ISO artifact
                                                     │                       ├→ optional ISO tests
                                      autounattend.xml + optional Tiny11      └→ optional Yandex import

1. UUP dump — fetches Windows update packages and builds a clean ISO
2. Tiny11 — removes bloatware, applies registry tweaks, bypasses system requirements
3. Unattended setup — embeds autounattend.xml in every final ISO

---

🚀 Quick Start (GitHub Actions)

1. Fork this repository
2. Go to Actions → Build Windows
3. Select parameters and click Run workflow
4. Download the ISO from Artifacts

---

⚙️ Workflow Inputs

Windows Configuration

Input	Options	Default
Version	Windows 11 25H2, 26H2, Beta, 26H1, Experimental, Future Platforms	Windows 11 25H2
Architecture	x64, arm64	x64
Edition	Pro, Home	Pro
Language	38 languages (ar-sa → zh-tw)	English (United States)
Revision	Optional build matching the selected version, for example 26340.9233	—

Build Options

Input	Description	Default
ESD	Use ESD compression	false
NetFx3	Add .NET Framework 3.5	false
Tiny11	Apply Tiny11 optimization	true
Yandex Disk	Privately upload the finished ISO and SHA256 sidecar to Yandex Disk	false
ISO test	Quickly validate the x64 ISO and verify Windows PE boot in QEMU	false
Full install test	Validate the ISO, install x64 Windows in QEMU, and audit the first boot	false

---

☁️ Optional Yandex Disk Upload

Enable Yandex Disk when starting the workflow to copy only that build's ISO and .sha256 file to private application storage. The ISO is published as an uncompressed GitHub artifact first, then Yandex Disk imports it directly from GitHub through a temporary signed URL. The Actions runner does not download or re-upload the large ISO.

The Yandex import runs as a separate job alongside any requested ISO tests. It verifies the remote file's exact size and SHA256 before uploading the small checksum sidecar. A Yandex failure is reported in that job's summary but does not discard the GitHub artifact or prevent the tests from running. The import job can be rerun without rebuilding the ISO.

One-time setup:

1. Register a Yandex OAuth application for API access.
2. Grant only cloud_api:disk.app_folder (access to the application's own Disk folder).
3. Copy the application's Client ID, open https://oauth.yandex.ru/authorize?response_type=token&client_id=<Client_ID>, allow access, and copy the returned access_token. Keep it private.
4. In the GitHub repository, open Settings → Secrets and variables → Actions, create the repository secret YANDEX_DISK_TOKEN, and paste the token as its value.

Uploaded files remain private and appear inside the application's folder under Apps / Приложения in Yandex Disk. Rebuilding an ISO with the same filename replaces that file; the workflow never creates a public link. GitHub also keeps a separate small verification artifact containing the .sha256 file and verification instructions.

---

🛠️ Tiny11 Optimization

When enabled, the built ISO is processed through Tiny11 which:

Removes Bloatware (40+ apps)

• Teams, OneDrive, Edge, Copilot, Recall
• Xbox Game Bar & Gaming Services
• Clipchamp, Paint 3D, 3D Viewer, Mixed Reality Portal
• Weather, News, Maps, Bing Search, Cortana
• Office Hub, Solitaire, Sticky Notes, To Do, and more

Registry Optimizations

• TPM 2.0 / Secure Boot / CPU / RAM requirement bypass
• All telemetry endpoints disabled
• Sponsored apps and consumer features blocked
• OneDrive backup prompts disabled
• BitLocker encryption disabled
• Chat icon / Widgets / Cortana startup removed

🧩 Unattended Setup (autounattend.xml)

Every ISO produced by uup-dump-get-windows-iso.ps1, including the Build Windows workflow, contains autounattend.xml at its root whether Tiny11 is enabled or not. The builder prepares the copy for the selected x64/ARM64 architecture and Pro/Home edition, while the tracked file remains the x64 Pro template.

During Windows Setup it provides:

• OOBE bypass (local account, no Microsoft account required)
• Additional app/capability/feature cleanup on first boot
• Core isolation (VBS/HVCI) disabled
• Privacy-focused defaults

Tiny11 still adds its separate offline image cleanup and registry changes when enabled.

---

✅ ISO Testing in GitHub Actions

Enable ISO test when manually starting Build Windows to run an optional test job after the ISO artifact is uploaded. The test:

• verifies the ISO boot files and x64 WIM/ESD metadata;
• runs wimverify against boot.wim and install.wim or install.esd;
• validates a root autounattend.xml when present;
• boots the ISO with UEFI in QEMU and waits up to 20 minutes for a Windows PE startup marker.

The boot test uses KVM when the runner exposes /dev/kvm and automatically falls back to TCG software emulation otherwise. Its answer file and startup marker are stored on a temporary raw FAT image; the guest signals startup over COM1, shuts down cleanly, and the runner reads the marker only after QEMU exits.

When Full install test is enabled, this separate Windows PE boot job is skipped. The full test performs the same structural and WIM/ESD checks first, then proceeds directly to installation, first boot, and audit. Selecting both checkboxes therefore does not download or test the ISO twice.

To test an existing image without rebuilding it, manually run Test Windows ISO from URL. Supply a direct HTTPS URL to the ISO and, optionally, its SHA256. A download page or a GitHub Actions artifact page is not a direct ISO URL. QEMU and WIM tools are installed only on the temporary Ubuntu runner.

Full installation test

Enable Full install test to perform a separate, opt-in integration test on an ephemeral Ubuntu runner. It first validates the ISO structure and WIM/ESD integrity without a redundant Windows PE boot, then requires KVM, creates a sparse 64 GiB virtual disk, installs image index 1 with a temporary CI answer-file overlay, boots the installed x64 system, runs the production FirstLogon.ps1, and returns a JSON audit report. The ISO and repository autounattend.xml are not modified.

When Tiny11 is enabled, the guest audit checks the setup logs, selected registry policies, disabled services, removed Appx packages, capabilities, optional features, and Edge/OneDrive paths. The complete JSON result is validated exclusively over COM1; the host then dismisses transient shell UI, captures a clean-desktop screenshot, and ends QEMU immediately without waiting for Windows to shut down. The raw FAT media supplies the CI answer file and audit script and retains diagnostic logs, but it is not accepted as a result channel. Compact logs are uploaded, and the virtual disk is always deleted. The job frees unused SDKs only on the temporary GitHub runner and requires at least 25 GiB of free workspace before starting.

The URL workflow provides matching Full installation test and Tiny11 audit checkboxes. Structural validation always runs; when the full installation test is selected, the separate Windows PE boot is skipped even if its checkbox is also selected. Disable Tiny11 audit when testing an ISO that was not produced by this repository.

---

💻 Manual Usage

Build ISO only (UUP dump)

pwsh uup-dump-get-windows-iso.ps1 win11-25h2 c:/output -architecture x64 -edition pro -lang en-us -esd -netfx3

Supported target keys:

Target	UUP branch	Allowed UUP ring
win11-25h2	26200.*	Retail / RP
win11-26h2	26300.*	Retail / RP
win11-beta	26220.*	WIS
win11-26h1	28000.*	Retail / RP
win11-experimental	26340.*	WIF
win11-future-platforms	Latest future platform build	Canary

Release-version targets accept only Retail or Release Preview candidates, preventing a newer Canary publication with the same base build from being selected silently.

Use -revision with a full build number matching the selected target, such as -revision 26340.9233 for Experimental. For fixed branches, a suffix such as -revision 9233 is also accepted. Future Platforms requires the full build number because its major build changes over time.

Optimize existing ISO (Tiny11)

# Option A: Pass ISO file path (auto-mounts)
.\scripts\tiny11maker-headless.ps1 -ISOPath "C:\path\to\windows.iso" -INDEX 1

# Option B: Pass mounted drive letter
.\scripts\tiny11maker-headless.ps1 -ISO E -INDEX 1

# With custom output path
.\scripts\tiny11maker-headless.ps1 -ISOPath "C:\path\to\windows.iso" -INDEX 1 -OutputPath "C:\output\optimized.iso"

---

🤖 Agent Documentation

Agent-facing documentation is available in AGENTS.md and .agents/:

• .agents/README.md — overview and operating rules
• .agents/repository-map.md — file responsibilities and generated artifacts
• .agents/workflow.md — GitHub Actions pipeline notes
• .agents/local-runbook.md — local commands, validation, and safety notes

---

📁 Repository Structure

windows-iso-builder/
├── .agents/
│   ├── README.md                   # Agent docs entry point
│   ├── local-runbook.md            # Local validation and safety notes
│   ├── repository-map.md           # File ownership map
│   └── workflow.md                 # GitHub Actions pipeline notes
├── .github/workflows/
│   ├── build.yml                    # Build and optional ISO test workflow
│   └── test-iso-url.yml             # Test an existing ISO from an HTTPS URL
├── scripts/
│   ├── test-windows-iso.ps1         # CI-only ISO and Windows PE smoke test
│   ├── test-windows-install.ps1     # CI-only full installation orchestrator
│   ├── test-installed-windows.ps1   # In-guest installed-state audit
│   ├── tiny11maker-headless.ps1     # Tiny11 optimizer
│   └── upload-yandex-disk.ps1       # Optional GitHub-to-Yandex server-side import
├── AGENTS.md                        # Root pointer for IDE/CLI agents
├── uup-dump-get-windows-iso.ps1     # UUP dump ISO builder
├── CustomAppsList.txt               # UUP dump app selection
├── autounattend.xml                 # OOBE bypass & post-install
├── .gitignore
├── README.md
└── LICENSE

---

💾 Requirements

For Building (GitHub Actions / Local)

Requirement	Minimum	Recommended
OS	Windows 10	Windows 11
PowerShell	5.1	7.0+
RAM	8GB	16GB+
Free Disk	30GB	50GB+
Permissions	Administrator	Administrator

For Running Built ISOs (with Tiny11)

System requirements are bypassed:

• Any x64 processor
• 1GB+ RAM (2GB+ recommended)
• 10GB+ storage
• No TPM / Secure Boot required

---

🙏 Credits

• UUP dump: uupdump.net / source
• Tiny11 builder: ntdevlabs/tiny11builder
• Tiny11 headless: kelexine

---

⚠️ Disclaimer

This tool is provided "as is" without warranty. You must have a valid Windows license. Use at your own risk.