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.
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)
(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:
- Use Github for Desktop application (GUI). This is the easiest at first.
- Use VSCode to edit PowerShell and commit to GitHub.
- Use Posh-Git module (CLI).
- Install Git for Windows
- many others
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: email@example.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:
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.