Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ili101/Module.Template
Powershell Module Template with GitHub, PowerShellGallery and AppVeyor.
https://github.com/ili101/Module.Template
Last synced: 7 days ago
JSON representation
Powershell Module Template with GitHub, PowerShellGallery and AppVeyor.
- Host: GitHub
- URL: https://github.com/ili101/Module.Template
- Owner: ili101
- Created: 2016-09-06T12:30:08.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2019-10-07T11:35:04.000Z (about 5 years ago)
- Last Synced: 2024-08-02T17:36:39.540Z (3 months ago)
- Language: PowerShell
- Homepage:
- Size: 94.7 KB
- Stars: 11
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
- jimsghstars - ili101/Module.Template - Powershell Module Template with GitHub, PowerShellGallery and AppVeyor. (PowerShell)
README
# Module.Template
Powershell Module Template with GitHub, PowerShellGallery, AppVeyor and Azure DevOps Pipelines integration.
Can be used as a starting point for your open source Module.
[](https://www.powershellgallery.com/packages/Module.Template/)
[](https://www.powershellgallery.com/packages/Module.Template/)
| CI System | Environment | Master | Beta |
|--------------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| AppVeyor | Windows, Core preview, Ubuntu | [](https://ci.appveyor.com/project/ili101/Module-Template) | [](https://ci.appveyor.com/project/ili101/Module-Template) |
| Azure DevOps | Windows | [](https://dev.azure.com/ili101/Module.Template/_build/latest?definitionId=1&branchName=master) | [](https://dev.azure.com/ili101/Module.Template/_build/latest?definitionId=1&branchName=Beta) |
| Azure DevOps | Windows (Core) | [](https://dev.azure.com/ili101/Module.Template/_build/latest?definitionId=1&branchName=master) | [](https://dev.azure.com/ili101/Module.Template/_build/latest?definitionId=1&branchName=Beta) |
| Azure DevOps | Ubuntu | [](https://dev.azure.com/ili101/Module.Template/_build/latest?definitionId=1&branchName=master) | [](https://dev.azure.com/ili101/Module.Template/_build/latest?definitionId=1&branchName=Beta) |
| Azure DevOps | macOS | [](https://dev.azure.com/ili101/Module.Template/_build/latest?definitionId=1&branchName=master) | [](https://dev.azure.com/ili101/Module.Template/_build/latest?definitionId=1&branchName=Beta) |
## Install
From repository (Recommended)
```PowerShell
Install-Module -Name Module.Template -Scope CurrentUser
```
From GitHub Branch (For testing)
```PowerShell
$Uri = 'https://raw.githubusercontent.com/ili101/Module.Template/master/Install.ps1'; & ([Scriptblock]::Create((irm $Uri))) -FromGitHub $Uri
```
## Instructions
### Setup
1. Create a GitHub Repository (Recommended name is the name of the Module) and clone the repository with VSCode.
2. Clone or download this repository and copy the files to your repository clone.
3. Remove/Replace/Edit/Rename the files `Module.Template.psm1`, `Module.Template.psm1`, `Invoke-ExampleCommand.ps1`, `Class.ps1` with your module files.
4. Remove/Replace/Edit/Rename the file `Tests\Invoke-ExampleCommand.Tests.ps1` with tests for your Module, you can create multiple test files in the folder ending with **.Tests.ps1**.
5. Edit `README.md`, `CHANGELOG.md` and the `Examples` folder to provide documentation for the Module.
6. `Install.ps1` is used to "build" the module and put it in the PowerShell Modules folder, adjust the `$IncludeFiles` and `$ExcludeFiles` variables if needed to configure which files and folders to copy from the source root folder. Can be used locally by executing `Install.ps1` or remotely from GitHub by the Install command mentiond in the `README.md`. (Also used in the CI procedure).
7. To use AppVeyor create an account on https://www.appveyor.com/ and connect it to the GitHub repository, the `appveyor.yml` file is used for the configuration.
8. To use Azure DevOps Pipelines create an account on https://dev.azure.com and connect it to the GitHub repository, the `azure-pipelines.yml` file is used for the configuration.
### CI Configuration and usage
**Triggers** - When Pushing a Commit to GitHub AppVeyor and Azure will be triggered unless the Commit contain only changes to the **.md** files or the skip tags [skip azp] (for Azure) and/or [skip av] (for AppVeyor) are added to the Commit name.
This behavior can be adjusted in the .yml files (`azure-pipelines.yml` do not support wildcards in the file names under trigger:paths:exclude).
Additionally to run a quick test locally in VSCode click F5 (verify debug is set to "PowerShell Pester Tests" in the debug section, this is set in `.vscode\launch.json`)
**PowerShell Version and OS** - AppVeyor set to test on Ubuntu, Windows Framework and Windows Core.
For Windows Core you can control the version by setting it in the line `- ps: '& .\CI\InstallPowerShell.ps1 -Version "7.0.0-preview.4"'` or comment the line out to use the default version.
For Ubuntu you can change or comment out the line with the `sudo apt-get install -y powershell-preview`.
Azure test on Windows Framework and Ubuntu, add/remove jobs in the .yml file to change it.
**Test Results** - The Pester test results are published to AppVeyor Tests tab by the `.\CI\CI.ps1 -Finalize` line, and to the Azure Tests tab by the `PublishTestResults@2` task.
**Artifacts** - Artifacts are Zip files created for later use, Artifact with the Windows Framework Module is uploaded to the AppVeyor Artifacts tab by the `.\CI\CI.ps1 -Artifact` line, Artifact with the Windows Framework Module and Artifact with the Git Source is uploaded to Azure by the `.\CI\CI.ps1 -Artifact` segment.
**Publish to PowerShell Gallery** - You can publish the Module to the PowerShell Gallery in 3 ways:
1. AppVeyor will publish the module automatically if the commit is made in the GitHub master branch and the module version in the .psd file is newer from the version in the gallery.
For this to work you need to go to [AppVeyor](https://www.appveyor.com/) > project > settings and under Environment add an "encrypted" environment variable named "NugetApiKey" with your PowerShell Gallery Key.
To disable this comment out the `- ps: '$null = Install-PackageProvider -Name NuGet -Force ; & .\CI\Publish.ps1'` line
1. In Azure you can publish the module manually from an Artifacts. For this to work you need to configure a "Releases" in Azure, I didn't find a way to configure it in the .yml, but I exported it to json `CI\Azure Publish config.json`, import it in [Azure](https://dev.azure.com) > Releases (You may need to create an empty releases, save it, view releases, New > Import and delete the empty release. Microsoft can create the worst interfaces known to man).
After importing in the Artifacts stage "Artifacts" will point to "Module.Template" delete "Artifacts" and recreate it pointing to your Project, If something show in red fix it (For example in "Publish Job" if the OS is not set select "windows-2019"). Then in the release configuration Variable tab add a "Secret" "Publish Stage" pipeline variable named "NugetApiKey" with your PowerShell Gallery Key.
To publish click "Create a new release" and select the Build version containing the Artifact to use for the release.
(You can delete the `CI\Azure Publish config.json` file)
1. You can also run `CI\Publish.ps1` locally with `-NugetApiKey `
**Publish to Docker Hub** - You can also publish the Module to Docker Hub (Can be good for testing new builds). You can optionally modify the Docker build by editing `CI\Dockerfile`.
The steps are the same as the PowerShell Gallery publish. In Azure > Releases import `CI\Azure Docker config.json`, Recreate "Artifacts" so it point to your Project, If something show in red fix it (Set the OS to Windows or Linux according to the OS configured in `CI\Dockerfile`), In "Docker Stage" > "buildAndPush" > "Container registry" set your Docker Hub credentials. You can delete the `CI\Azure Docker config.json` file.
**ScriptAnalyzer** - A ScriptAnalyzer report is generated and saved in Azure Pipelines > Artifacts > Source > `ScriptAnalyzer.xlsx`. In a PR the report will include the PR analysis and the target branch analysis.
To disable this comment out the `- powershell: './CI/CI.ps1 -Analyzer'` section in the Azure yaml.
## Changelog
[CHANGELOG.md](https://github.com/ili101/Module.Template/blob/master/CHANGELOG.md)
## Contributing
If you fund a bug or added functionality or anything else just fork and send pull requests. Thank you!
Ideas for new functionality and feature requests are welcomed, you can post your ideas in the "Issues" section.
## To do
* Noting for now, You can open an Issues if something is needed.
## Examples
[Invoke-ExampleCommand.Examples.ps1](https://github.com/ili101/Module.Template/blob/master/Examples/Invoke-ExampleCommand.Examples.ps1)
```PowerShell
Invoke-ExampleCommand
```
