New Module helper function

The Story

Recently I’ve decided to clean up my code a little bit, generalize it, and put it on GitHub.

I also wanted to eventually publish it to PowerShell Gallery. But to make it more challenging I wanted to automate it. My idea was to use:

  • GitHub- to store my code, my precious PowerShell modules
  • AppVeyor – for automatic builds, tests and deployment
  • PowerShell Gallery as final destination for my modules

Great inspiration was Warren’s post. Thanks to it I was able to gather all the knowledge required for this task. I greatly encourage you to read it.

The Idea

Anyone can download files from GitHub and use. But it’s better to publish PowerShell Modules to PowerShell Gallery and allow anyone to just type Install-Module MyModule and voila. To speed up the process and eliminate human errors I’ll use AppVeyor – it will look at any changes made to specified repository. If there’s any commit to the repo, it will spin a new VM, clone the repository, run any tests that will be included and if no errors are found – publish to the PS Gallery. After this the VM will be destroyed. And it’s all free (if open source projects are used). VM in AppVeyor will use additional modules (PSDeploy, BuildHelpers, Psake and Pester) but that will be transparent and won’t require any additional tasks – thanks to my helper function.

For Appveyor to work it requires a specific folder and files structure. Warren’s post goes into more details about it.

Recently PowerShell Plaster was created (GitHub) which can greatly speed up the process of creating a new project or module. It is really great. I’ll be looking into it to create a template that will include all my requirements. For now – I’m pleased with simple module creation provided by my function.

Step by step

Steps required to accomplish this are:

  • Create GitHub and PowerShell Gallery account.
  • Create GitHub repository
  • Clone it to your workstation
  • Create all necessary folders and files
  • Get PowerShell Gallery API key
  • Create AppVeyor account using GitHub login
  • Encrypt PS Gallery key in AppVeyor
  • Include the key in the appveyor.yml file
  • Create new project in AppVeyor
  • Commit and sync to github repo

This shouldn’t take longer than 10 minutes and is done only once. If you’d like to create another module in the future – it will take less than 2 minutes.

Let’s start then.

Create GitHub and PS Gallery accounts

Creating GitHub and PowerShell Gallery accounts is pretty straightforward.

For GitHub – go to their home page, fill in the details

Choose your plan. Free is good for start:

You can skip the next step if you wish – little Skip this step next to Green Submit button. You’re done.

For PowerShell Gallery – go to their home page, choose register

Select your account type:

You can create a free Microsoft personal account or use one you already have (Office 365 accounts works as well)

Log in

(screen from work account login type)

Fill in the details and confirm registration

Create GitHub repository

Then create your first repository on GitHub.

Fill in all the information. It’s best to initalize repo with Readme.md file. You will use this for repostiory “welcome page”. Also choose your License. I’m using MIT. Then click Create repository:

Clone repository to desktop

There are different ways you can clone the repository to your workstation:

I’ll guide you through installation and usage of GitHub for Desktop application.

GitHub for Desktop

Download, install and run the application.

On the welcome screen enter your GitHub login information

On the Configure screen replace your email address with following: username@users.noreply.github.com

This will keep your email private and not show it in commits

Once done, go to Options

Set up your default path where you’ll be keeping your repositories. Set PowerShell as a default shell.

Save it. Then on the main menu, choose to clone repository:

This will create a folder in the path you provided.

Create all necessary folders and file

This is the fun part. This is where my function kicks in. Download it from my GitHub Repo. Include it in your current session. Provide some basic details and … you’re nearly done.

You’ll get nicely verbose messages:

What happens here:

  • A new PowerShell module is created in C:\Repo\GIT\TestRepository
  • All necessary folders are created
  • All necessary files, which are generic, are downloaded from my GitHub repo.
  • All necessary information is updated in psd1 and psm1 files

All you need to do now is to provide the encrypted key to AppVeyor for PowerShell Gallery.

Get PowerShell Gallery API key

Log in to your PowerShell Gallery profile and locate your API key:

Copy that key. It will be needed in a moment. Keep it safe.

Create AppVeyor account using GitHub login

Sign up to AppVeyor using your github account:

Go to your profile and select Encrypt Data:

Then copy your API key from PowerShell Gallery. Don’t worry, it will be encrypted and you’ll be provided with encrypted value. Only your appveyor account will be able to use this and push changes to PowerShell Gallery.

Remember, NEVER share your API key from PowerShell Gallery.

Now, open appveyor.yml file in your repository and replace ‘SecureNugetApiKeyComesHere’ value with the encrypted value you have received. To get best view, open the file in Notepad++ or PowerShell ISE. Files downloaded from GitHub have formatting which Windows doesn’t like too much 🙂

Create new project in AppVeyor

Select GitHub, your repository and click Add

This way we inform AppVeyor to watch for changes in this repository. Last step now. Finally.

Commit and sync to github repo

Last step is to commit files locally and then to the repository. Switch back to GitHub for Desktop.

  • Enter some meaningful commit description.
  • Commit to master. Now your files are ‘snapshot’ localy on your drive.
  • Sync to GitHub master – now you’re sending files to GitHub

Let’s see what is appveyor doing about it. After a few seconds it shows up in the console in appveyor.

Once the build starts (it can take w few minutes) we can see the console output:

Ok. But what about pushing it to PowerShell Gallery? To have that done, just put !deploy in the commit message or description. Remember – it has to be !deploy. Otherwise you won’t see module published to PS Gallery. Always read the log output if in trouble:

Summary

Creating a PowerShell Module is pretty easy. New-ModuleManifest with parameters and you’re done. Commiting changes to GitHubisn’t too complicated as well. Publishing items to PowerShell Gallery is not a rocket science either. But combining it together in an automated way can take a few hours of your life at first. Trust me. I hope that thanks to my function and this tutorial it will be a breeze for you.

If you have any comments – feel free to contact me.

Advertisements

One thought on “New Module helper function

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s