psmodulecache

This action makes caching PowerShell modules from the PowerShell Gallery easy for Linux, Windows and macOS runners. Basically, it builds all of the required input for actions/cache.

If you're using GitHub Actions to test projects that rely on PowerShell modules like PSFramework or dbatools, this caches those modules so they aren't downloaded from the PowerShell Gallery over and over again. It is possible to configure a cache with an automatic update, the module search can target in PSGallery or other PSRepositories requiring or not credential.

Warning GitHub will deprecate all versions of this Action earlier than v5.1 on June 1, 2023. It is recommended that you update all of your workflows now to use psmodulecache@v5.1 or greater.

How to use it
Usage
Parameters syntax
Error message
Examples of settings
Cache key construction method
Cache limits
Acceptance of a license
Known issues

How to use it <a name="howto"></a>

Just copy the code below and modify the line modules-to-cache: PSFramework, PoshRSJob, dbatools with the modules you need.

    - name: Install and cache PowerShell modules
      uses: potatoqualitee/psmodulecache@v6.0
      with:
        modules-to-cache: PSFramework, PoshRSJob, dbatools

PSModuleCache returns the newest version of a module if no parameters are used that limit the version.

If you need to use RequiredVersion, add a colon then the version: modules-to-cache: PSFramework, dbatools:1.1.0

    - name: Install and cache PowerShell modules
      uses: potatoqualitee/psmodulecache@v6.0
      with:
        modules-to-cache: PSFramework, dbatools:1.1.0

For a cache with an update search each time your Action is executed, add two colon: modules-to-cache: PSFramework, Pester::, "dbatools::"

In this case set the updatable parameter to true.

    - name: Install and cache PowerShell modules
      uses: potatoqualitee/psmodulecache@v6.0
      with:
        modules-to-cache: PSFramework,Pester::, dbatools:1.1.0
        updatable: true

If you need to install a prerelease, use the modules-to-cache-prerelease parameter : modules-to-cache-prerelease: PnP.PowerShell:1.11.44-nightly

    - name: Install and cache PowerShell modules
      uses: potatoqualitee/psmodulecache@v6.0
      with:
        modules-to-cache: PSFramework,Pester:4.10.1, dbatools:1.1.0
        modules-to-cache-prerelease: PnP.PowerShell:1.11.44-nightly

Note: Under Windows Powershell if the module targets both versions of Powershell, then PSCore uses the path of Powershell v5.1.

It is therefore not necessary to create an installation (a Step) for each version of Powershell.

On the other hand under Windows with PS Core the same module targeting two versions will be only installed in the specific directory of PS Core.

Usage <a name="usage"></a>

Pre-requisites

Create a workflow .yml file in your repositories .github/workflows directory. Example workflows are available below. For more information, reference the GitHub Help Documentation for Creating a workflow file.

Cache scopes

The cache is scoped to the key and branch. The default branch cache is available to other branches.

Inputs

modules-to-cache - A comma-separated list of PowerShell module names to install and then cache. Each module name can specify a version or auto-update. A module name can be prefixed with a repository name separated by a backslash.
modules-to-cache-prerelease -A comma-separated list of PowerShell module names marked as a prerelease, to install and then cache. Each module name can specify a version or auto-update. A module name can be prefixed with a repository name separated by a backslash. Keep in mind that when searching for a prerelease 'Find-Module' may return a stable version.
shell - The default shell you'll be using. Defaults to pwsh. Recognized shells are 'powershell' and 'pwsh', you can specify one or the other, or both. Duplicate shell names are silently removed and therefore do not generate an error. The use of shell names allows to configure the installation path of the module :
- For Windows Powershell : $env:ProgramFiles\WindowsPowerShell\Modules
- For Powershell Core (under Windows) : $env:ProgramFiles\PowerShell\Modules
- For Powerhsell Core (under Linux or MacOS) : /usr/local/share/powershell/Modules/
updatable - Triggers, on each execution of the action, an update for the module names that request it. Defaults to false.
prefixidentifier - Prefixes the cache key name with the Workflow name ($env:GITHUB_WORKFLOW). Used to group cache keys. Defaults to false.

Prerelease module versions

The following text details the rule for building a prerelease version number. Prerelease module versions

Search in repositories

The modules indicated in the `modules-to-cache' or 'modules-to-cache-prerelease' parameter can come from PsRepositories declared in the Runner (server).

To declare PsRepositories again, you must save them before calling the 'Cache' step :

      - name: Setting additional PSRepositories
        shell: pwsh
        run: |
            Register-PSRepository -Name 'OttoMatt' -publishlocation='https://www.myget.org/F/ottomatt/api/v2/package' -sourcelocation='https://www.myget.org/F/ottomatt/api/v2' -InstallationPolicy 'trusted'

      - name: Cache modules
        id: psmodulecache
        uses: potatoqualitee/psmodulecache@v6.0
        with:
           modules-to-cache: InvokeBuild,OptimizationRules
           ....

The 'OptimizationRules' module is not published on PSGallery but on MyGet.

Note

In the event of multiple presence of the same module name in many repositories, psmodulecache will raise an error. The use of the following syntax will be necessary to specify from which repository the module is retrieved:

      - name: Cache modules
        id: psmodulecache
        uses: potatoqualitee/psmodulecache@v6.0
        with:
           modules-to-cache: InvokeBuild,OttoMatt\OptimizationRules
           ....

The syntax 'OttoMatt\OptimizationRules is nammed 'Repository qualified module name'.

Parameters syntax <a name="parameterssyntax"></a>

Syntax for 'modules-to-cache' parameter

InvokeBuild

Simple module name, we save the last stable version found. For this syntax, we do not specify a version number.

The cache content for this module is not updated until the cache lifetime has expired. An Updatable cache will force its update.

InvokeBuild:5.0.0

A simple module name followed by a single colon and a three-part version number (mandatory), the requested stable version is recorded.

The cache content for this module will always be the same, regardless of the cache lifetime.

PnP.PowerShell::

Simple module name followed by two colons. For this syntax, we do not specify a version number. The last stable version found is saved.

An update search is started each time your Action is executed.

The cache content is updated as soon as a new version is released or the cache lifetime has expired.

Note : YAML may need to use double quotation marks: modules-to-cache: "Pester::"

Syntax for 'modules-to-cache-prerelease' parameter

The syntax is the same as for the 'module-to-cache' parameter but concerns only prerelease versions.

Pester

Simple module name, we save the last prerelease version found. For this syntax, we do not specify a version number.

The cache content for this module is not updated until the cache lifetime has expired. An Updatable cache will force its update.

PnP.PowerShell:1.11.22-nightly

A simple module name followed by a single colon and a four-part version number (mandatory), the requested prerelease is saved.

The cache content for this module will always be the same, regardless of the cache lifetime.

PSScriptAnalyzer::

Simple module name followed by two colons. For this syntax, we do not specify a version number. The last prerelease found is saved or the latest stable version if there is no prerelease or if the latest stable version is greater than the last published prerelease.

An update search is started each time your Action is executed.

The cache content is updated as soon as a new prerelease is released or the cache lifetime has expired.

Note : YAML may need to use double quotation marks: modules-to-cache-prerelease: "Pester::"

Get a stable version and a prerelease version of a module

We may want to install a stable version and the last prerelease :

modules-to-cache: PnP.PowerShell:1.11.0
modules-to-cache-prerelease: PnP.PowerShell

Or a previous version and the latest version :

modules-to-cache: PnP.PowerShell:1.10.0,PnP.PowerShell

You can also force the update for prereleases :

modules-to-cache: PnP.PowerShell:1.11.0
modules-to

Psmodulecache

Install / Use

README