- 30 Dec 2021
- 3 Minutes to read
-
Print
-
DarkLight
-
PDF
HOWTO: Use Approved PowerShell Gallery Packages (Optionally Offline)
- Updated on 30 Dec 2021
- 3 Minutes to read
-
Print
-
DarkLight
-
PDF
Using Only Approved PowerShell Gallery Packages (Optionally Offline)
Using ProGet, teams can restrict access to Microsoft’s public PowerShell module repository, the PowerShell Gallery, ensuring only approved packages are ever used.
By default, PowerShell will attempt to pull and publish from powershellgallery.com
. That’s not great for teams that that work offline or teams that need a package approval workflow in place.
A package approval process is just like a code review but for packages, your team would like to use. It can be as casual as sending an email to an approver OR it could have a formal gated process where multiple people sit in a room and discuss it.
This article will run through a standard example scenario of a company, Kramerica, configuring ProGet to create a package approval workflow to ensure only approved packages from the PowerShell Gallery are available for all the operations team to use. This configuration would also allow the feed to be used offline.
Step 1: Create an Unapproved Feed
First, we'll create an unapproved PowerShell feed where unverified packages from the PowerShell Gallery will be stored.
To start, we will create a feed that connects to powershellgallery.com
. Navigate to Feeds > Create New Feed > PowerShell Modules
Note that feed usage is set to "Free/Open Source packages", since it will be connecting to the PowerShell Gallery.
Step 2: Create Connector to the PowerShell Gallery
Now that the feed is created, we need to connect it to the PowerShell Gallery so it can pull public packages. After creating feeds, ProGet will prompt to create a connector, so we can simply click "Create Connector" and save.
This feed is now connected to the PowerShell Gallery and after restrictions are configured, network engineers will be able to access this feed to review and approve packages.
Step 3: Create Approved Feed
For a package to be promoted from one feed to another, there must be multiple feeds. Following the exact steps, we will create another feed that will only have verified and approved PowerShell packages.
We'll name the feed kramerica-approved-powershell and select "Validated/promoted" packages" for the feed usage. This is where verified and approved packages will be promoted to.
Again, like step 1, we want to give our operation team access to this feed. To do so, navigate to “Administrative Overview” > “Security & Authentication” > “Users & Tasks” > “Tasks” >
Step 4: Configure a Package Promotion Pipeline
A package promotion pipeline is an optional practice to limit which feed packages can be promoted to. This ensures that packages promoted from a non-production feed (like Testing) can only be promoted to a production feed.
To set up a package promotion pipeline, we'll navigate to Feeds > "kramerica-unapproved-powershell" > "Manage Feed" > "Other Settings", then click "Promote to Feed" and select kramerica-approved-powershell.
Step 5: Set Permissions
There are many ways to configure security access controls for uses and groups in ProGet. For this example, we'll say that only network engineers can promote packages to the “kramerica-approved-powershell” feed since they're trained to verify the quality, licenses, and vulnerabilities of open-source packages. To ensure this rule, we'll set up a new permission. By default, only administrators have assigned permissions.
To start, navigate to Settings > "Users & Tasks" > "Tasks". Here you'll see many different levels of permissions.
For this example, we'll click on "Add Permissions" and fill out the following dialog to give the "Network Engineers" user group permission to "Promote Packages" from the “kramerica-unapproved-powershell” feed.
Next, we'll give the "Operations Team" user group permission to "View and Download" packages from the “kramerica-approved-powershell” feed in the same way.
After saving these two privileges, our task overview page looks like this:
How to Use Your PowerShell Feed
To use this newly created feed, we'll first need to find the endpoint URL on the Feed Overview page, and register it as a source.
To register this endpoint, we'll use the Register-PSRepository
cmdlet with the following parameters:
-Name
- the name of the approved packages feed-SourceLocation
- the Endpoint URL of the approved packages feed
However, PowerShell will still try to pull modules from the PowerShell Gallery, so we need to unregister it using the Unregister-PSRepository
cmdlet. That just requires one parameter (Name
), which is PSGallery
by default.
Example
For example, using the feed names we created earlier:
Register-PSRepository -Name kramerica-approved-powershell -SourceLocation https://«host-name»/nuget/kramerica-approved-powershell
Unregister-PSRepository -Name PSGallery
After that, PowerShell will only use the approved packages feed for modules, without needing to access the public PowerShell Gallery.
Note that, if you want to publish packages to this feed, you'll need to also specify the PublishLocation
parameter as well. This would be the same as SourceLocation
.