Catesta-GHActions.md

Catesta - GitHub Actions Integration

Synopsis

Scaffolds a new PowerShell module project intended for CI/CD workflow using GitHub Actions.

Getting Started

Note: Before getting started you should have a basic idea of what you expect your module to support. If your module is cross-platform, or you want to test different versions of PowerShell you should run multiple build types.

Windows PowerShell	Windows pwsh	Linux	MacOS

1. You will need a GitHub account.

2. Create a new repository and clone to your local dev device

3. Create your project using Catesta

   New-PowerShellProject -CICDChoice 'GitHubActions' -DestinationPath C:\path\GitHubActions

   1. The Plaster logo will be displayed and you will see your first prompt
   2. Enter the name of the module: Name of your module
   3. Enter a description for the module: Description of what your module does
   4. Enter the version number of the module (0.0.1): Starting version #
   5. Enter your full name: Module author name
   6. Would you like to generate a Changelog file?
   7. Select a License for your module. (Help deciding: https://choosealicense.com/)
   8. Would you like to generate a Code of Conduct file?
   9. Would you like to generate a Contributing guidelines file?
   10. Would you like to specify a coding style for the project? [S] Stroustrup [O] OTBS [A] Allman [N] None [?] Help (default is "S"): The preferred coding style for the project
   11. Would you like to use platyPS to generate help documentation files for your project? Creates Markdown & external help for your module
   12. Select desired pipeline job configurations. (If your module is cross-platform you should select multiple)
       • [W] Windows - PowerShell
       • [C] Core (Windows)- pwsh
       • [L] Linux
       • [M] MacOS

4. Write a kick-ass module (the hardest part)

   • All build testing can be done locally by navigating to src and running Invoke-Build
   • If using VSCode as your primary editor you can use tasks to perform various local actions
     • Examples:
       • Press Ctrl+P, then type 'task .' - Runs complete build (all tasks)
       • Press Ctrl+P, then type 'task Test' - Invokes all Pester Unit Tests
       • Press Ctrl+P, then type 'task Analyze' - Invokes Script Analyzer checks
       • Press Ctrl+P, then type 'task DevCC' - Generates generate xml file to graphically display code coverage in VSCode using Coverage Gutters

5. The comment based help in your functions will be used to generate/update markdown docs for your module in the docs folder.

6. Upload to your desired repository which now has a triggered/monitored build action.

7. Evaluate results of your build and display your GitHub Actions badge proudly!

Notes

Additional Reading:

• Automating your workflow with GitHub Actions
• Virtual environments for GitHub-hosted runners
• Software installed on GitHub-hosted runners
• Using a specific shell
• Workflow syntax for GitHub Actions
• Where does the upload go?
• Building and testing PowerShell

Diagrams

GitHub Actions

Example Projects

• Catesta
• pwshPlaces
• ApertaCookie