By the evening of November 8, OrphanedSid had green CI on both shells and docs checked against the code. The last thing left was pushing a tag.
I was nervous releasing this to the Gallery. It’s very niche, after all. Hopefully it’s useful to someone, though, and discovery via a public repo and the Gallery can increase those odds.
A release workflow that assumes it’ll be wrong
The PowerShell Gallery won’t let you take a version back. You can unlist a package, which hides it from search, but it stays downloadable by exact version. Once 1.0.0 is up, 1.0.0 means whatever got uploaded. The release workflow’s header says as much:
| |
Pushing a v* tag runs the whole quality-gates workflow again first, because a tag can point at any commit, including one that never went through a pull request. Then the publish job checks the tag against the manifest:
After that, Publish-Module.ps1 copies an allowlist of files into a staging folder, refuses to go further if that version is already on the Gallery, and then imports the staged copy in a fresh process to prove it works before anything is uploaded:
A module can import fine and still be missing a private helper that only runs when a command does. Calling one pure private function through the module catches that. Test-SIDFormat was picked because it needs no directory.
The first tag never left the runner
The v1.0.0 tag went up at about 18:50 my time. All three quality gates passed. The publish job failed at that check:
Look at the path: /home/runner. The publish job ran on ubuntu-latest. Test-SIDFormat builds a System.Security.Principal.SecurityIdentifier, and that type comes from System.Security.Principal.Windows. On Linux, .NET throws PlatformNotSupportedException for it. So the module was fine, and the check that proves a staged module works couldn’t run on the machine doing the staging.
My other templates use an Ubuntu runner, and I tend to go back to that well first on new projects.
Nothing was uploaded, so 1.0.0 was still free on the Gallery. The fix was one line in release.yml, with the reason next to it:
The v1.0.0 tag moved to the merge commit with that change and went up again. Moving a published tag is usually bad manners. Moving one that never produced a release, before anyone could have installed it, is the case it’s fine for.
The second run passed every gate, proved the staged copy, and published. OrphanedSid 1.0.0 was on the Gallery at about 19:14.
Restoring one object didn’t work
OrphanedSid: Find, Remove, Restore was already in progress. I wanted real output from the published package, so I installed 1.0.0 from the Gallery on the lab DC and ran a full cycle: find, remove, find, restore, find. The restore by OU worked. Then I tried the README’s rollback, which pipes each object from a removal’s CSV into Restore-OrphanedSidBackup one at a time:
That was 19:28, about fifteen minutes after the release.
The single letter in BackupFile was the clue. For a single object, the restore workflow found the backups whose file names matched, sorted them newest first, and took the first:
With more than one match, $sortedMatches is an array and [0] is a path. With exactly one, Sort-Object hands back the string itself, and [0] on a string is its first character. Every backup path started with C:\. Wrapping the sort in @() keeps one match a one-element array, and the new tests run the real workflow against Clixml backups in TestDrive. Three of the four fail without the fix.
The failed attempts didn’t change anything in the directory. They just didn’t restore.
The egg on my face, finding this immediately after publishing. I couldn’t believe it.
A worse bug behind the fix
Fixing the [0] meant reading how the workflow picked a backup in the first place, and that was worse than the indexing. It matched on a substring of the file name:
| |
A backup’s file name is its sanitized DN, so a restore of CN=User1 also matched CN_User10_.... It matched the same CN in every other OU, too. The newest match won. Then the restore rewrote the object recorded inside that backup, not the one you asked for, and reported Success = True naming the other object.
With the indexing fixed, that bug became reachable. 1.0.0 couldn’t restore a single object at all. A 1.0.1 with only the first fix could restore the wrong one and call it a success.
The second fix stops trusting file names. It opens every backup in the folder and reads the ObjectDN it recorded:
A single-object restore takes only backups whose recorded DN equals the target, ignoring case. A container restore takes the target and anything ending in ,<target>, so OU=Sales doesn’t pull in OU=PreSales. An object with several backups in the folder is restored once, from the newest. New tests cover the look-alikes: User1 against User10, the same CN in another OU, letter case, a target whose only backups belong to look-alikes, OU=Sales against OU=PreSales, a container with one backup, and two runs in one folder. Five of the seven fail with only the first fix in place.
The live check used a decoy. After a removal on the lab DC, a fake backup of the second group went into the folder with the first group’s file-name prefix and a newer date. A restore of the first group used the first group’s own backup and put back 34 entries. The second group stayed at 33 with no orphan, where it should’ve been.
1.0.1
Both fixes merged at 20:07, and the v1.0.1 tag went through the same workflow on the Windows runner. OrphanedSid 1.0.1 was on the Gallery at 20:15, an hour after 1.0.0.
1.0.0 is still there, and it’ll stay there.
