Repository navigation
Publish to the PowerShell Gallery — the README's install command does not work yet #5
Description
The first code block in the README is this:
Install-Module IntuneGraph -Scope CurrentUser # (coming to PSGallery)It does not work. IntuneGraph is not on the PowerShell Gallery, so the first command
a visitor runs fails, and the comment explaining why is inside the block they have
already pasted. docs/discoverability.md names the Gallery
as the intended install route and the surface that PSGallery search reads — so this is
the gap between what the project says about itself and what it ships.
Publishing is one-way in the way that matters: a version can be unlisted, but the
version number can never be reused. So 0.2.0 goes out once, and the manifest needs to
be right before it does.
What the manifest is missing
Looking at src/IntuneGraph/IntuneGraph.psd1:
- No
CompatiblePSEditions.PowerShellVersion = '5.1'and the README both claim
Windows PowerShell 5.1 and PowerShell 7+. The Gallery's edition filter is driven by
CompatiblePSEditionstogether with the reservedPSEdition_Desktopand
PSEdition_Coretags. Neither is present, so after publishing the module would sit
outside edition-filtered search — for a module whose whole 5.1 floor is a deliberate
reach for admins still on Windows PowerShell, that is the wrong filter to be missing
from. Tagscarries the OS compatibility tags but not the edition ones.Windows,
macOSandLinuxare there and correct.PSEdition_DesktopandPSEdition_Core
are not.- No
IconUri. The listing renders with a placeholder, next to modules that do not. - The two descriptions have drifted. The manifest's
Descriptionand the GitHub
repository description are close but not the same sentence. Worth converging them, if
only so a change to the pitch has one place to happen.
There is no release path
CI runs PSScriptAnalyzer and Pester across the matrix, which is the hard part and it is
already done. What does not exist:
- no publish job in
.github/workflows/ - no
Publishtask inbuild.ps1— it knowsTest,AnalyzeandFixtures
So publishing today means running Publish-Module by hand from a workstation with a
NuGet API key on the command line, which is exactly the sort of step that gets done once
and then done wrong the second time.
Proposed
- Manifest: add
CompatiblePSEditions = @('Desktop','Core'), addPSEdition_Desktop
andPSEdition_CoretoTags, addIconUri, alignDescriptionwith the
repository description. build.ps1 -Task PublishwrappingPublish-Module, taking the key from an
environment variable and never a parameter default..github/workflows/release.yml, triggered on av*tag, gated on the existing CI
job passing, with the API key in a repository secret.- README: replace the
(coming to PSGallery)comment with a real version badge, so
the install line stops being a promise.
Acceptance criteria
-
Install-Module IntuneGraph -Scope CurrentUserworks from a clean machine on both
Windows PowerShell 5.1 and PowerShell 7+ - The Gallery listing shows an icon, the correct project, licence and release-notes
links, and appears under both PowerShell edition filters - Pushing a
v*tag publishes, and does so only when CI is green - The API key exists only as a repository secret — not in
build.ps1, not in a
default parameter value, not in shell history - The README install block has no explanatory comment left in it
Related: docs/discoverability.md, which records the Gallery
as one of the three surfaces this project is meant to be found on, and notes that the
manifest Tags and the GitHub topics are separate lists that need to stay in step.
Activity
juandresrodca commentedon Sep 13, 2026
The blocker turned out to be the name, not the manifest.
IntuneGraphon the PowerShell Gallery is already taken by an unrelated module from another author (five versions, the latest January 2025) that uploads, assigns and removes Intune apps. So the README'sInstall-Module IntuneGraphwas never failing: it was installing that module, write cmdlets included.A Gallery package name has to equal the module name, so #6 renames the module to IntuneGraphKit and implements everything proposed here: the edition metadata,
IconUri, an alignedDescription,build.ps1 -Task Publishreading the key from the environment only, and av*-tag release workflow gated on CI and on the tag matchingModuleVersion. Cmdlet names, the repository and the MCP server name stay IntuneGraph.After #6 merges, what remains is adding the
PSGALLERY_API_KEYsecret and tagging the first release. This stays open untilInstall-Module IntuneGraphKitworks from a clean machine.juandresrodca commentedon Sep 30, 2026
Release notes for the first Gallery version are now prepared on
main(8318f79). Whilewriting them, two things came out of the repository state that change what "what remains"
means here — neither is in the list above, and one of them is a version number that cannot
be taken back.
The manifest version collides with a changelog entry that already claims to be released
src/IntuneGraphKit/IntuneGraphKit.psd1still readsModuleVersion = '0.2.0', andCHANGELOG.mdalready carries a## [0.2.0] - 2026-09-06section. So taggingv0.2.0today satisfies the release workflow's tag-matches-manifest check and publishes 0.2.0
to the Gallery — a package whose contents are the renamed
IntuneGraphKit, described by achangelog section written before the rename existed. The rename is in Unreleased, not in
0.2.0.
That is the trap this issue opens by warning about: the version number can never be reused,
so the mismatch would be permanent and the fix would have to be a second publish.
The rename is breaking for anyone who wrote
Import-Module IntuneGraph, and pre-1.0 SemVerputs a breaking change in the minor position, so the first Gallery version should be
0.3.0. 8318f79 names it as such in the changelog and spells out the migration; the
manifest bump is deliberately not in that commit, because it is source and because it is
the step that arms the tag.
There are no tags at all, so the release workflow has never run
git tagis empty and/releasesis empty. 0.1.0 and 0.2.0 were never tagged and have noGitHub release, which means:
Install-Module IntuneGraphKit -RequiredVersion 0.1.0has nothing to resolve, and nov0.1.0...v0.2.0comparison exists — 8318f79 says so in the changelog rather thanshipping links that 404;
v*tag publishes, and does so only when CI isgreen" is still untested, so the first tag push is both the first release and the first
exercise of the pipeline;
release.ymlfires on anyv*tag, so
git tag v0.2.0 <old-sha>would attempt a publish rather than just labelling apoint in history. If backfilled tags are wanted for the comparison links, the workflow
needs to distinguish a release tag from a history tag first — worth its own issue.
What is actually left
ModuleVersion = '0.3.0'in the manifest (source, so not something the docsmaintenance run touches).
PSGALLERY_API_KEYrepository secret. I cannot see from here whether it isalready set — reading secrets is outside the scopes this maintenance work runs with — so
it is worth confirming before the tag rather than discovering it in a failed job.
## [0.3.0]with the date, and add the[0.3.0]comparison link.git tag v0.3.0 && git push origin v0.3.0, then watch the Release workflow: CI matrixfirst, tag-matches-manifest second, publish last.
Only step 4 is irreversible, and by then everything checkable has been checked.