PowerShell scripts have become indispensable in today’s administration of operating systems and applications. The classic administration with the help of an MMC is increasingly receding into the background. As a replacement for the purely graphical management of a local or hybrid infrastructure, Microsoft provides us with the browser-based Windows Admin Center.

The automation and simplified operation of your IT platform requires PowerShell scripts that are individually adapted to your requirements. The development of a script does not end with the first functional version. Rather, a script evolves with new requirements. And this, ideally, in a team of several administrators.

Exactly here a source code management for your PowerShell scripts helps you.

Why do I need source code management?

When you start using PowerShell scripts for your IT environment, in most cases you start with a script that you found in a search engine using a search query. You save the file in a more or less arbitrary file directory on your local computer. When you make changes to this script, you always overwrite the previous file or make new copies of the original file with customized file names. This procedure is very error-prone and not suitable for working in a team of multiple administrators.

Source code management for your PowerShell scripts has the following advantages:

• Script Versioning: Each script is versioned with the option to rollback a previous version.
• Script Check-out/Check-In: Fork from a current version to develop a new version without affecting the current version
• Integration: Deploy PowerShell scripts from external sources that have been customized and extended for the local environment.
• Traceability: Audit logging of changes with information on who made the change
  
  

Best Practices for source code management

There are many ways to implement source code management. Perhaps the company already has a central source code administration that is used by a development department. In this case, the easiest way is to have a separate area, the so-called repository, in this source code management. Make sure that you can manage the folder and authorization structure independently in a central repository.

If you are not yet using source code management in your company, there are various solutions available. These solutions include Team Foundation Server, CVS, Subversion or Git, to name just a few. The first question you should ask yourself is whether you want to build source code management on your own servers in your internal IT infrastructure or whether you prefer to use a cloud-based solution.

Personally I use GitHub as a unified source code management for my different projects. These projects include not only PowerShell, but also C# and Web projects. GitHub is a web-based source code management and offers a free plan for single users as well as several paid plans for the professional use of development teams. For use in a business context, I definitely recommend a paid team plan. The advantage of such a plan is that the ownership and administration is assigned to a generic company account and not to a single person.

Tip: Learn how ScriptRunner helps you to develop scripts in a team and organize them centrally

As part of the administration, you create one or more locations for storing PowerShell scripts. These locations are called repositories. For each repository you create, you can specify who has access to the repository and whether it is a public or private repository. If you want to use source code management only for internal corporate use, create private repositories.

Whether you create a repository for each administration team or a separate repository for each individual script depends entirely on your needs. Since you have to configure the permissions for each individual repository, this variant is associated with increased effort, but offers granular control. A separate target directory is required for each individual repository in the local file system of your workstation or server.

First create a directory below which you download the required repositories. This process is called check-out. The following example shows a folder structure for the Active Directory, Exchange, Office 365, and SharePoint teams.

For a better overview, the individual scripts are structured by name. This allows you to save configuration files and other information in the context of a script. Every administrator can now download the scripts necessary for his daily work, update them if necessary and upload them again. Uploading changes, including new directories and files, is called check-in or commit.

In contrast to a grouping according to administrative teams, a local directory structure for individual repositories per script looks as follows:

You will quickly see the difference. If you have a large number of PowerShell scripts, this approach quickly becomes confusing. I use both variants. My public PowerShell scripts are each stored in their own repository. This allows me to control every single release of a script. At the same time I have a few private repositories where I collect and maintain thematically ordered scripts for daily use.

In the local file system this mixture is as follows:

The green framed directories are checked out repositories of single PowerShell scripts. The orange bordered directory is a repository that contains a whole collection of scripts for setting up and managing a Microsoft Azure Lab.

Readme files

Of course, you maintain the help information of a PowerShell script within a script. They even provide application examples that can be queried using the Get-Help cmdlet. This information is useful and necessary when you work directly within a PowerShell session.

Readme files are more useful for viewing a Web-based repository and finding a suitable cmdlet. For each repository, create a readme file that describes the contents of the repository and its purpose. You should also list the contact persons or persons responsible with contact data. You should also create a readme file for each script that describes the purpose of the script and provides application examples. Such readme files must be created in Markdown format.

Clients for source code management

You need a suitable client for the check-out, commit, and other access actions to a repository. Different software solutions are available depending on the source code management used and the local operating system. There are also script editors that already have built-in source code management. Whether you prefer to work with the command line version of Git, with the file explorer extension Tortoise or with the Git extension for Visual Studio Code is up to you. Each of your administrators will have personal preferences for their daily work. And that’s a good thing.

Instead, make sure that the tools you use are always up-to-date and fully compatible with source code management.

PowerShell scripts in productive operation

Never use your PowerShell scripts in the direct storage path of a connected repository. PowerShell scripts sometimes create script-related log files that are stored in the same file path. For security reasons, this data is not suitable for storage in source code management.

To run PowerShell scripts productively, I recommend that you build a separate directory structure that is not part of a repository. Use a top-level directory name that clearly indicates that these are productive scripts.

Ideally, you should also keep the repository’s directory structure. This will help you and your teammates find their way around and avoid mistakes.
Alternatively, you can work with protected branches within a repository. For a functional version of a script, you create a copy branch that is protected against deletion and unauthorized overwriting. As soon as a new version of the script can be used productively, a request for merging the source code (merge request) must be made for a protected branch. You must explicitly release the merge. In this way you can ensure that only successfully tested code is used.

Concluding words

One more word about safety. Regardless of whether you want to use GitHub or any other web-based source code management solution, always make sure you configure access to the repositories correctly. Secure source code management allows you to enable multi-factor authentication. Use this option to protect the source code of your scripts from unauthorized access.

Feel free to use my public PowerShell scripts as templates.

I hope you enjoy PowerShell and look forward to your feedback.

Related Links

• What is Windows Admin Center?,
  https://docs.microsoft.com/en-us/windows-server/manage/windows-admin-center/understand/what-is?wt.mc_id=MVP
• GitHub, https://github.com/
• Best practices for protected branches,
  https://github.community/t5/Support-Protips/Best-practices-for-protected-branches/ba-p/10224
• Mastering Markdown, https://guides.github.com/features/mastering-markdown/
• TortoiseGit, https://tortoisegit.org/
• TortoiseSVN, https://tortoisesvn.net/
• Visual Studio Code, https://code.visualstudio.com/download
• My public GitHub repositories, https://github.com/Apoc70
• My PowerShell scripts around Exchange Server and Office 365, http://scripts.granikos.eu
• Script-Development with ScriptRunner: https://www.scriptrunner.com/en/software/script-development/