Skip to content

Commit a214cf4

Browse files
OctomergerOctomerger
authored
repo sync
2 parents 2484cd3 + 5c4f233 commit a214cf4

File tree

6 files changed

+246
-3
lines changed

6 files changed

+246
-3
lines changed

‎assets/images/help/repository/actions-failed-pester-test.png

120 KB
Loading

‎content/actions/guides/building-and-testing-powershell.md

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
---
2+
title: Building and testing PowerShell
3+
intro: You can create a continuous integration (CI) workflow to build and test your PowerShell project.
4+
product: '{% data reusables.gated-features.actions %}'
5+
versions:
6+
free-pro-team: '*'
7+
enterprise-server: '>=2.22'
8+
---
9+
10+
{% data reusables.actions.enterprise-beta %}
11+
{% data reusables.actions.enterprise-github-hosted-runners %}
12+
13+
### Introduction
14+
15+
This guide shows you how to use PowerShell for CI. It describes how to use Pester, install dependencies, test your module, and publish to the PowerShell Gallery.
16+
17+
{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes PowerShell and Pester. For a full list of up-to-date software and the pre-installed versions of PowerShell and Pester, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".
18+
19+
### Prerequisites
20+
21+
You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)."
22+
23+
We recommend that you have a basic understanding of PowerShell and Pester. For more information, see:
24+
- [Getting started with PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/learn/ps101/01-getting-started)
25+
- [Pester](https://pester.dev)
26+
27+
{% data reusables.actions.enterprise-setup-prereq %}
28+
29+
### Adding a workflow for Pester
30+
31+
To automate your testing with PowerShell and Pester, you can add a workflow that runs every time a change is pushed to your repository. In the following example, `Test-Path` is used to check that a file called `resultsfile.log` is present.
32+
33+
This example workflow file must be added to your repository's `.github/workflows/` directory:
34+
35+
{% raw %}
36+
```yaml
37+
name: Test PowerShell on Ubuntu
38+
on: push
39+
40+
jobs:
41+
pester-test:
42+
name: Pester test
43+
runs-on: ubuntu-latest
44+
steps:
45+
- name: Check out repository code
46+
uses: actions/checkout@v2
47+
- name: Perform a Pester test from the command-line
48+
shell: pwsh
49+
run: Test-Path resultsfile.log | Should -Be $true
50+
- name: Perform a Pester test from the Tests.ps1 file
51+
shell: pwsh
52+
run: |
53+
Invoke-Pester Unit.Tests.ps1 -Passthru
54+
```
55+
{% endraw %}
56+
57+
* `shell: pwsh` - Configures the job to use PowerShell when running the `run` commands.
58+
* `run: Test-Path resultsfile.log` - Check whether a file called `resultsfile.log` is present in the repository's root directory.
59+
* `Should -Be $true` - Uses Pester to define an expected result. If the result is unexpected, then {% data variables.product.prodname_actions %} flags this as a failed test. For example:
60+
61+
![Failed Pester test](/assets/images/help/repository/actions-failed-pester-test.png)
62+
63+
* `Invoke-Pester Unit.Tests.ps1 -Passthru` - Uses Pester to execute tests defined in a file called `Unit.Tests.ps1`. For example, to perform the same test described above, the `Unit.Tests.ps1` will contain the following:
64+
```
65+
Describe "Check results file is present" {
66+
It "Check results file is present" {
67+
Test-Path resultsfile.log | Should -Be $true
68+
}
69+
}
70+
```
71+
72+
### PowerShell module locations
73+
74+
The table below describes the locations for various PowerShell modules in each {% data variables.product.prodname_dotcom %}-hosted runner.
75+
76+
|| Ubuntu | macOS | Windows |
77+
|------|-------|------|----------|
78+
|**PowerShell system modules** |`/opt/microsoft/powershell/7/Modules/*`|`/usr/local/microsoft/powershell/7/Modules/*`|`C:\program files\powershell\7\Modules\*`|
79+
|**PowerShell add-on modules**|`/usr/local/share/powershell/Modules/*`|`/usr/local/share/powershell/Modules/*`|`C:\Modules\*`|
80+
|**User-installed modules**|`/home/runner/.local/share/powershell/Modules/*`|`/Users/runner/.local/share/powershell/Modules/*`|`C:\Users\runneradmin\Documents\PowerShell\Modules\*`|
81+
82+
### Installing dependencies
83+
84+
{% data variables.product.prodname_dotcom %}-hosted runners have PowerShell 7 and Pester installed. You can use `Install-Module` to install additional dependencies from the PowerShell Gallery before building and testing your code.
85+
86+
{% note %}
87+
88+
**Note:** The pre-installed packages (such as Pester) used by {% data variables.product.prodname_dotcom %}-hosted runners are regularly updated, and can introduce signficant changes. As a result, it is recommended that you always specify the required package versions by using `Install-Module` with `-MaximumVersion`.
89+
90+
{% endnote %}
91+
92+
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
93+
94+
For example, the following job installs the `SqlServer` and `PSScriptAnalyzer` modules:
95+
96+
{% raw %}
97+
```yaml
98+
jobs:
99+
install-dependencies:
100+
name: Install dependencies
101+
runs-on: ubuntu-latest
102+
steps:
103+
- uses: actions/checkout@v2
104+
- name: Install from PSGallery
105+
shell: pwsh
106+
run: |
107+
Set-PSRepository PSGallery -InstallationPolicy Trusted
108+
Install-Module SqlServer, PSScriptAnalyzer
109+
```
110+
{% endraw %}
111+
112+
{% note %}
113+
114+
**Note:** By default, no repositories are trusted by PowerShell. When installing modules from the PowerShell Gallery, you must explicitly set the installation policy for `PSGallery` to `Trusted`.
115+
116+
{% endnote %}
117+
118+
#### Caching dependencies
119+
120+
You can cache PowerShell dependencies using a unique key, which allows you to restore the dependencies for future workflows with the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
121+
122+
PowerShell caches its dependencies in different locations, depending on the runner's operating system. For example, the `path` location used in the following Ubuntu example will be different for a Windows operating system.
123+
124+
{% raw %}
125+
```yaml
126+
steps:
127+
- uses: actions/checkout@v2
128+
- name: Setup PowerShell module cache
129+
id: cacher
130+
uses: actions/cache@v2
131+
with:
132+
path: "~/.local/share/powershell/Modules"
133+
key: ${{ runner.os }}-SqlServer-PSScriptAnalyzer
134+
- name: Install required PowerShell modules
135+
if: steps.cacher.outputs.cache-hit != 'true'
136+
shell: pwsh
137+
run: |
138+
Set-PSRepository PSGallery -InstallationPolicy Trusted
139+
Install-Module SqlServer, PSScriptAnalyzer -ErrorAction Stop
140+
```
141+
{% endraw %}
142+
143+
### Testing your code
144+
145+
You can use the same commands that you use locally to build and test your code.
146+
147+
#### Using PSScriptAnalyzer to lint code
148+
149+
The following example installs `PSScriptAnalyzer` and uses it to lint all `ps1` files in the repository. For more information, see [PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer).
150+
151+
{% raw %}
152+
```yaml
153+
lint-with-PSScriptAnalyzer:
154+
name: Install and run PSScriptAnalyzer
155+
runs-on: ubuntu-latest
156+
steps:
157+
- uses: actions/checkout@v2
158+
- name: Install PSScriptAnalyzer module
159+
shell: pwsh
160+
run: |
161+
Set-PSRepository PSGallery -InstallationPolicy Trusted
162+
Install-Module PSScriptAnalyzer -ErrorAction Stop
163+
- name: Lint with PSScriptAnalyzer
164+
shell: pwsh
165+
run: |
166+
Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues
167+
$errors = $issues.Where({$_.Severity -eq 'Error'})
168+
$warnings = $issues.Where({$_.Severity -eq 'Warning'})
169+
if ($errors) {
170+
Write-Error "There were $($errors.Count) errors and $($warnings.Count) warnings total." -ErrorAction Stop
171+
} else {
172+
Write-Output "There were $($errors.Count) errors and $($warnings.Count) warnings total."
173+
}
174+
```
175+
{% endraw %}
176+
177+
### Packaging workflow data as artifacts
178+
179+
You can upload artifacts to view after a workflow completes. For example, you may need to save log files, core dumps, test results, or screenshots. For more information, see "[Persisting workflow data using artifacts](/github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)."
180+
181+
The following example demonstrates how you can use the `upload-artifact` action to archive the test results received from `Invoke-Pester`. For more information, see the [`upload-artifact` action](https://github.com/actions/upload-artifact).
182+
183+
{% raw %}
184+
```yaml
185+
name: Upload artifact from Ubuntu
186+
187+
on: [push]
188+
189+
jobs:
190+
upload-pester-results:
191+
name: Run Pester and upload results
192+
runs-on: ubuntu-latest
193+
steps:
194+
- uses: actions/checkout@v2
195+
- name: Test with Pester
196+
shell: pwsh
197+
run: Invoke-Pester Unit.Tests.ps1 -Passthru | Export-CliXml -Path Unit.Tests.xml
198+
- name: Upload test results
199+
uses: actions/upload-artifact@v2
200+
with:
201+
name: ubuntu-Unit-Tests
202+
path: Unit.Tests.xml
203+
if: ${{ always() }}
204+
```
205+
{% endraw %}
206+
207+
The `always()` function configures the job to continue processing even if there are test failures. For more information, see "[always](/actions/reference/context-and-expression-syntax-for-github-actions#always)."
208+
209+
### Publishing to PowerShell Gallery
210+
211+
You can configure your workflow to publish your PowerShell module to the PowerShell Gallery when your CI tests pass. You can use repository secrets to store any tokens or credentials needed to publish your package. For more information, see "[Creating and using encrypted secrets](/github/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
212+
213+
The following example creates a package and uses `Publish-Module` to publish it to the PowerShell Gallery:
214+
215+
{% raw %}
216+
```yaml
217+
name: Publish PowerShell Module
218+
219+
on:
220+
release:
221+
types: [created]
222+
223+
jobs:
224+
publish-to-gallery:
225+
runs-on: ubuntu-latest
226+
steps:
227+
- uses: actions/checkout@v2
228+
- name: Build and publish
229+
env:
230+
NUGET_KEY: ${{ secrets.NUGET_KEY }}
231+
shell: pwsh
232+
run: |
233+
./build.ps1 -Path /tmp/samplemodule
234+
Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose
235+
```
236+
{% endraw %}

‎content/actions/guides/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ You can use {% data variables.product.prodname_actions %} to create custom conti
2929
{% link_in_list /about-continuous-integration %}
3030
{% link_in_list /setting-up-continuous-integration-using-workflow-templates %}
3131
{% link_in_list /building-and-testing-nodejs %}
32+
{% link_in_list /building-and-testing-powershell %}
3233
{% link_in_list /building-and-testing-python %}
3334
{% link_in_list /building-and-testing-java-with-maven %}
3435
{% link_in_list /building-and-testing-java-with-gradle %}

‎content/actions/learn-github-actions/introduction-to-github-actions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ The workflow is an automated procedure that you add to your repository. Workflow
3434

3535
#### Events
3636

37-
An event is a specific activity that triggers a workflow. For example, activity can originate from {% data variables.product.prodname_dotcom %} when someone pushes a commit to a repository or when an issue or pull request is created. You can also use the repository dispatch webhook to trigger a workflow when an external event occurs. For a complete list of events that can be used to trigger workflows, see [Events that trigger workflows](/actions/reference/events-that-trigger-workflows).
37+
An event is a specific activity that triggers a workflow. For example, activity can originate from {% data variables.product.prodname_dotcom %} when someone pushes a commit to a repository or when an issue or pull request is created. You can also use the [repository dispatch webhook](/rest/reference/repos#create-a-repository-dispatch-event) to trigger a workflow when an external event occurs. For a complete list of events that can be used to trigger workflows, see [Events that trigger workflows](/actions/reference/events-that-trigger-workflows).
3838

3939
#### Jobs
4040

‎content/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,15 @@ If you decide you don't want the changes in a topic branch to be merged to the u
4646

4747
{% data reusables.files.choose-commit-email %}
4848

49+
{% note %}
50+
51+
**Note:** The email selector is not available for rebase merges, which do not create a merge commit, or for squash merges, which credit the user who created the pull request as the author of the squashed commit.
52+
53+
{% endnote %}
54+
4955
6. Click **Confirm merge**, **Confirm squash and merge**, or **Confirm rebase and merge**.
5056
6. Optionally, [delete the branch](/articles/deleting-unused-branches). This keeps the list of branches in your repository tidy.
51-
57+
5258
The repository may be configured so that the head branch for a pull request is automatically deleted when you merge a pull request. For more information, see "[Managing the automatic deletion of branches](/github/administering-a-repository/managing-the-automatic-deletion-of-branches)."
5359

5460
{% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" or currentVersion ver_gt "[email protected]" %}

‎contributing/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Here, you'll find additional information that might be helpful as you work on a
66

77
- [development](./development.md) - steps for getting this app running on your local machine
88
- [content markup reference](./content-markup-reference.md) - how to use markup and features specific to the GitHub Docs site
9-
- [content style guide](./content-style-guide) - style guidance specific to GitHub Docs content and additional resources for writing clear, helpful content
9+
- [content style guide](./content-style-guide.md) - style guidance specific to GitHub Docs content and additional resources for writing clear, helpful content
1010
- [deployments](./deployments.md) - how our staging and production environments work
1111
- [liquid helpers](./liquid-helpers.md) - using liquid helpers for versioning in our docs
1212
- [localization checklist](./localization-checklist.md) - making sure your content is ready to be translated

0 commit comments

Comments
 (0)