The Best 3 Ways to Organize your PowerShell Modules in Source Control
by Crista Perlton, on Jun 28, 2021 8:49:48 AM
Your PowerShell modules are a POWERFUL and integral part of your development process. Modules are a part of the PowerShell and can revolutionize your PowerShell experience (for better - or possibly for worse.)
Source control management (SCM) helps you make sure it's for the better. However, SCM only works as long as it's organized.
Unsure if you're properly organizing your source code? Unsure how to start organizing your source code? This article a straightforward best-practice guide for how to do source control management and create your own PowerShell modules including the best 3 ways to organize your PowerShell modules in source control.
Source Control: The Golden Standard in PowerShell Module Management
Source Control Management provides you with a history of your module’s source code checkouts, edits, and commits. Since PowerShell modules become a part of the PowerShell on a workstation, team members can (and should) add important contextual information when committing code.
A very common Source Control workflow is Gitflow. The basic steps are:
- Create a “branch,” which is an exact copy of the main version, but which is segregated from the main code
- Make edits in the branch
- Commit changes, which kicks off several approval stages
If there are no conflicts, in-branch changes merge into the main.
Source control management is so important when storing and updating your source code for your PowerShell modules since small changes to modules affect every single workstation using them.
However, it’s important to note: just using source control workflows isn’t good enough when working with modules – you need to organize your source code.
How to Organize your Modules
There are many ways to organize your source code. The best option is the one that integrates best with your organization. Below are a few options for organizing your modules that we’ve seen work.
Option 1: Organize by Project
Breaking down projects into categories like new products, maintenance, etc.
Why it’s Good: This is a great system for team cooperation and streamlining working on your modules.
What to Do: Create multiple folders for each different module or set of scripts under the same project. Splitting these into their own folders means they can be built and versioned separately from one another.
Possible Issues: The problem with project organization is it’s difficult to organize at a very granular level. Should this go in project A or project B? This is a multi-purpose module, should it go in subfolder X or Z? And since projects are typically temporary, when your team archives a project, they will effectively be archiving these scripts with it.
Option 2: Organize by Department & Team
Breaking down folders by department name (Sales, Accounting, Marketing, etc.)
Why it’s Good: Projects can cross teams, but organizational departments and teams are vertical by nature. This means you can make sure certain extremely sensitive or important scripts would be inaccessible to any below a certain part of the organizational chart (e.g., maybe only managers in the Finance department can get into X folder).
What to Do: Create folders first by department and then by role in that department. Then use credentials (or even Active Directory if possible) to block certain people's access to different folders.
Possible Issues: The main disadvantage of organizing by department/team is that you are creating information silos. Not all the scripts in “Finance” can/will ever be accessed by other members of your team. They will never be able to use/improve/learn from those scripts.
Option 3: Organize by Technology
Create folders based on technology the module interacts with.
A simple example of this would be separating your Azure modules from your local mail service modules.
Why it’s Good: This form of organization really helps level up knowledge of more junior (lower XP) team members and if you’ve read any of our other PowerShell articles, you know that’s a good thing.
What to Do: Create folders based on the various technologies being used on your team (like Azure). Sometimes it's really straightforward. For example, if you need to do Azure storage maintenance, then you would look in the Azure folder, and the Storage subfolder.
Possible Issues: Other times it's not straightforward. For example, if you need to file the "QuickBooks maintenance" module. Should that go in the "QuickBooks" technology folder? But wait, QuickBooks is an accounting tool, so maybe it belongs in the "Accounting" folder? Or maybe this is part of the QuickBooks Migration Project, so should it go there?
How you choose to organize isn’t that important. What’s important is that you’re organizing.
Creating a PowerShell Module
Now that you’ve got a strong handle on SCM and have planned out how you want to organize your modules, the next step is creating some modules of your own. You can create a module from the source code in source control.
Modules combine several PowerShell functions into a single reusable and easily sharable resource. You can put lots of files such as .dlls and tools in a module. But this is the bare minimum - a .psm1 file.
After creating your module, you’ll have to create a PowerShell Module Manifest. These are required for publishing modules to a repository. A module manifest is a PowerShell data file (.psd1) that, is simply an “about” file for your module that contains information about the module, including the version number, copyright, exported variables, etc. Microsoft has a full list of parameters you can use.
PowerShell modules have to be downloaded directly from a repository to work so the next step is to store your module. By default, PowerShell will try to publish to and pull modules from the PowerShell Gallery, Microsoft’s public PowerShell module repository. However, your first-party modules are incredibly valuable assets. In most cases, you probably don’t want to share them with the world on third-party, public, repositories.
The great news is it’s easy to create and manage your own private PowerShell repositories using ProGet. ProGet’s feeds allow you to safely store and share PowerShell modules with all members of your organization without the risks associated with a public repository.
Wrapping up and Next Steps
PowerShell modules are a powerful resource that will help you and your team “level up” your PowerShell. However, they also have the capability of causing an incredible amount of damage. Using source control management and ProGet will help your team avoid those pitfalls and stay out of module hell.
ProGet's feeds enable you to safely store and share your first-party PowerShell modules with all members of your organization without the risks associated with a public repository in its free-forever version.