Skip to content

Commit 6921b3e

Browse files
MariusStorhaugMariusStorhaug
authored
Initial version
1 parent 7f1d0ed commit 6921b3e

File tree

14 files changed

+401
-2
lines changed

14 files changed

+401
-2
lines changed

‎.gitattributes‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Needed for publishing of examples, build worker defaults to core.autocrlf=input.
2+
* text eol=autocrlf
3+
4+
*.mof text eol=crlf
5+
*.sh text eol=lf
6+
*.svg eol=lf
7+
8+
# Ensure any exe files are treated as binary
9+
*.exe binary
10+
*.jpg binary
11+
*.xl* binary
12+
*.pfx binary
13+
*.png binary
14+
*.dll binary
15+
*.so binary

‎.github/linters/.markdown-lint.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
###########################
2+
## Markdown Linter rules ##
3+
###########################
4+
5+
# Linter rules doc:
6+
# - https://github.com/DavidAnson/markdownlint
7+
8+
###############
9+
# Rules by id #
10+
###############
11+
MD004: false # Unordered list style
12+
MD007:
13+
indent: 2 # Unordered list indentation
14+
MD013:
15+
line_length: 808 # Line length
16+
MD026:
17+
punctuation: ".,;:!。，；:" # List of not allowed
18+
MD029: false # Ordered list item prefix
19+
MD033: false # Allow inline HTML
20+
MD036: false # Emphasis used instead of a heading
21+
22+
#################
23+
# Rules by tags #
24+
#################
25+
blank_lines: false # Error on blank lines

‎.github/release.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#configuring-automatically-generated-release-notes
2+
3+
changelog:
4+
categories:
5+
- title: Breaking Changes
6+
labels:
7+
- Major
8+
- Breaking
9+
- title: New Features
10+
labels:
11+
- Minor
12+
- Feature
13+
- Improvement
14+
- Enhancement
15+
- title: Other Changes
16+
labels:
17+
- '*'

‎.github/workflows/Auto-Release.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Auto-Release
2+
3+
run-name: "Auto-Release - [${{ github.event.pull_request.title }} #${{ github.event.pull_request.number }}] by @${{ github.actor }}"
4+
5+
on:
6+
pull_request_target:
7+
branches:
8+
- main
9+
types:
10+
- closed
11+
- opened
12+
- reopened
13+
- synchronize
14+
- labeled
15+
16+
concurrency:
17+
group: ${{ github.workflow }}
18+
19+
permissions:
20+
contents: write
21+
pull-requests: write
22+
23+
jobs:
24+
Auto-Release:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout Code
28+
uses: actions/checkout@v4
29+
30+
- name: Auto-Release
31+
uses: PSModule/Auto-Release@v1
32+
env:
33+
GITHUB_TOKEN: ${{ github.token }} # Used for GitHub CLI authentication
34+
with:
35+
IncrementalPrerelease: false

‎.github/workflows/Linter.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: Linter
2+
3+
run-name: "Linter - [${{ github.event.pull_request.title }} #${{ github.event.pull_request.number }}] by @${{ github.actor }}"
4+
5+
on: [pull_request]
6+
7+
jobs:
8+
Lint:
9+
name: Lint code base
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout repo
13+
uses: actions/checkout@v4
14+
15+
- name: Lint code base
16+
uses: github/super-linter@latest
17+
env:
18+
GITHUB_TOKEN: ${{ github.token }}

‎.github/workflows/Workflow-Test.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: Workflow-Test
2+
3+
run-name: "Workflow-Test - [${{ github.event.pull_request.title }} #${{ github.event.pull_request.number }}] by @${{ github.actor }}"
4+
5+
on: [pull_request]
6+
7+
jobs:
8+
WorkflowTestDefault:
9+
uses: ./.github/workflows/workflow.yml
10+
secrets: inherit
11+
with:
12+
Name: PSModule
13+
TestProcess: true

‎.github/workflows/workflow.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Process-PSModule
2+
3+
on:
4+
workflow_call:
5+
secrets:
6+
APIKey:
7+
description: The API key to use when publishing modules
8+
required: true
9+
inputs:
10+
Name:
11+
type: string
12+
description: The name of the module to process. Scripts default to the repository name if nothing is specified.
13+
required: false
14+
SkipTests:
15+
type: boolean
16+
description: Whether to skip tests.
17+
required: false
18+
default: false
19+
TestProcess:
20+
type: boolean
21+
description: Whether to test the process.
22+
required: false
23+
default: false
24+
25+
env:
26+
GITHUB_TOKEN: ${{ github.token }} # Used for GitHub CLI authentication
27+
28+
jobs:
29+
Process-PSModule:
30+
name: Process module
31+
runs-on: ubuntu-latest
32+
steps:
33+
- name: Checkout Code
34+
uses: actions/checkout@v4
35+
36+
- name: Initialize environment
37+
uses: PSModule/Initialize-PSModule@v1
38+
39+
- name: Test source code
40+
uses: PSModule/Test-PSModule@v1
41+
if: ${{ inputs.SkipTests != true }}
42+
with:
43+
Name: ${{ inputs.Name }}
44+
Path: src
45+
RunModuleTests: false
46+
47+
- name: Build module
48+
uses: PSModule/Build-PSModule@v1
49+
with:
50+
Name: ${{ inputs.Name }}
51+
Path: src
52+
ModulesOutputPath: outputs/modules
53+
DocsOutputPath: outputs/docs
54+
55+
- name: Test built module
56+
uses: PSModule/Test-PSModule@v1
57+
if: ${{ inputs.SkipTests != true }}
58+
with:
59+
Name: ${{ inputs.Name }}
60+
Path: outputs/modules
61+
62+
- name: Publish module
63+
uses: PSModule/Publish-PSModule@v1
64+
with:
65+
Name: ${{ inputs.Name }}
66+
ModulePath: outputs/modules
67+
DocsPath: outputs/docs
68+
APIKey: ${{ secrets.APIKEY }}
69+
WhatIf: ${{ inputs.TestProcess }}

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## Ignore Visual Studio Code temporary files, build results, and
2+
## files generated by popular Visual Studio Code add-ons.
3+
##
4+
## Get latest from https://github.com/github/gitignore/blob/master/Global/VisualStudioCode.gitignore
5+
.vscode/*
6+
!.vscode/settings.json
7+
!.vscode/extensions.json
8+
*.code-workspace
9+
10+
# Local History for Visual Studio Code
11+
.history/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 PSModule
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 111 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,111 @@
1-
# Actions
2-
Repo for GitHub actions and workflows
1+
# Process-PSModule
2+
3+
A workflow for the PSModule process, stitching together the `Initialize`, `Build`, `Test`, and `Publish` actions to create a complete
4+
CI/CD pipeline for PowerShell modules. The workflow is used by all PowerShell modules in the PSModule organization.
5+
6+
## Specifications and practices
7+
8+
Process-PSModule follows:
9+
10+
- [Test-Driven Development](https://testdriven.io/test-driven-development/) using [Pester](https://pester.dev) and [PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules)
11+
- [GitHub Flow specifications](https://docs.github.com/en/get-started/using-github/github-flow)
12+
- [SemVer 2.0.0 specifications](https://semver.org)
13+
- [Continiuous Delivery practices](https://en.wikipedia.org/wiki/Continuous_delivery)
14+
15+
## How it works
16+
17+
The workflow is designed to be trigger on pull requests to the repository's default branch.
18+
When a pull request is opened, closed, reopened, synchronized (push), or labeled, the workflow will run.
19+
Depending on the labels in the pull requests, the workflow will result in different outcomes.
20+
21+
- [Initialize-PSModule](https://github.com/PSModule/Initialize-PSModule/) - To prepare the runner for all requirements of the framework.
22+
- [Test-PSModule](https://github.com/PSModule/Test-PSModule/) - Testing the source code using only PSScriptAnalyzer and the PSModule test suites.
23+
- [Build-PSModule](https://github.com/PSModule/Build-PSModule/) - To compile the repository into an efficient PowerShell module.
24+
- [Test-PSModule](https://github.com/PSModule/Test-PSModule/) - Testing the compiled module using PSScriptAnalyzer, PSModule test suites and custom module tests.
25+
- [Publish-PSModule](https://github.com/PSModule/Publish-PSModule/) - Publish the module to the PowerShell Gallery, publish docs to GitHub Pages, and create a release on the GitHub repository.
26+
27+
To use the workflow, create a new file in the `.github/workflows` directory of the module repository and add the following content.
28+
<details>
29+
<summary>Workflow suggestion</summary>
30+
31+
```yaml
32+
name: Process-PSModule
33+
34+
on:
35+
pull_request:
36+
branches:
37+
- main
38+
types:
39+
- closed
40+
- opened
41+
- reopened
42+
- synchronize
43+
- labeled
44+
45+
concurrency:
46+
group: ${{ github.workflow }}
47+
48+
permissions:
49+
contents: write
50+
pull-requests: write
51+
52+
jobs:
53+
Process-PSModule:
54+
uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v1
55+
secrets: inherit
56+
57+
```
58+
</details>
59+
60+
## Usage
61+
62+
### Inputs
63+
64+
| Name | Type | Description | Required | Default |
65+
| ---- | ---- | ----------- | -------- | ------- |
66+
| `Name` | `string` | The name of the module to process. This defaults to the repository name if nothing is specified. | `false` | N/A |
67+
| `SkipTests` | `boolean` | Whether to skip the tests. | false | `false` |
68+
| `TestProcess` | `boolean` | Whether to test the process. | false | `false` |
69+
70+
### Secrets
71+
72+
The following secrets are **required** for the workflow to run:
73+
74+
| Name | Location | Description | Default |
75+
| ---- | -------- | ----------- | ------- |
76+
| `GITHUB_TOKEN` | `github` context | The token used to authenticate with GitHub. | `${{ secrets.GITHUB_TOKEN }}` |
77+
| `APIKey` | GitHub secrets | The API key for the PowerShell Gallery. | N/A |
78+
79+
## In detail
80+
81+
The following steps will be run when the workflow triggers:
82+
83+
- Checkout Code [actions/checkout](https://github.com/actions/checkout/)
84+
- Checks out the code of the repository to the runner.
85+
- Initialize environment [PSModule/Initialize-PSModule](https://github.com/PSModule/Initialize-PSModule/)
86+
- Test source code [PSModule/Test-PSModule](https://github.com/PSModule/Test-PSModule/)
87+
- Looks for the module in the `src` directory and runs the PSScriptAnalyzer and PSModule testing suite on the code.
88+
- Build module [PSModule/Build-PSModule](https://github.com/PSModule/Build-PSModule/)
89+
- Build the manifest file for the module.
90+
- Compiles the `src` directory into a PowerShell module and docs.
91+
- The compiled module is output to the `outputs/modules` directory.
92+
- The compiled docs are output to the `outputs/docs` directory.
93+
- Test built module [PSModule/Test-PSModule](https://github.com/PSModule/Test-PSModule/)
94+
- Looks for the module in the `outputs/modules` directory and runs the PSScriptAnalyzer, PSModule testing suite and the custom module tests from the `tests` directory on the code.
95+
- Publish module [PSModule/Publish-PSModule](https://github.com/PSModule/Publish-PSModule/)
96+
- Calculates the next version of the module based on the latest release and labels on the PR.
97+
- Publishes the module to the PowerShell Gallery using the API key stored in as a secret named `APIKey`.
98+
- Publishes the docs to GitHub Pages from the `outputs/docs` directory.
99+
- Creates a release on the GitHub repository with the source code.
100+
101+
## Permissions
102+
103+
The action requires the following permissions:
104+
105+
If running the action in a restrictive mode, the following permissions needs to be granted to the action:
106+
107+
```yaml
108+
permissions:
109+
contents: write # Required to create releases
110+
pull-requests: write # Required to create comments on the PRs
111+
```

0 commit comments

Comments
 (0)