Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.
Introdução
Este guia mostra como usar PowerShell para CI. Ele descreve como usar o Pester, instalar dependências, testar seu módulo e publicar na Galeria do PowerShell.
Executores hospedados em GitHub têm um cache de ferramentas com software pré-instalado que inclui PowerShell e Pester.
Para ver uma lista completa dos programas de software atualizados e das versões pré-instaladas do PowerShell e do Pester, confira "Especificações dos executores hospedados no GitHub".
Pré-requisitos
Você deve estar familiarizado com o YAML e a sintaxe do GitHub Actions. Para obter mais informações, confira "Aprenda a usar o GitHub Actions".
Recomendamos que você tenha um entendimento básico de PowerShell e Pester. Para obter mais informações, consulte:
Usar executores auto-hospedados no GitHub Enterprise Server
Ao usar ações de instalação (como actions/setup-LANGUAGE
) no GitHub Enterprise Server com executores auto-hospedados, talvez seja necessário configurar o cache de ferramentas nos executores que não têm acesso � Internet. Para obter mais informações, confira "Como configurar o cache de ferramentas em executores auto-hospedados sem acesso � Internet".
Adicionar um fluxo de trabalho ao Pester
Para automatizar o seu teste com PowerShell e Pester, você pode adicionar um fluxo de trabalho que é executado toda vez que uma alteração é carregada no seu repositório. No exemplo a seguir, Test-Path
é usado para verificar se um arquivo chamado resultsfile.log
está presente.
Este exemplo de arquivo de fluxo de trabalho precisa ser adicionado ao diretório .github/workflows/
do repositório:
name: Test PowerShell on Ubuntu
on: push
jobs:
pester-test:
name: Pester test
runs-on: ubuntu-latest
steps:
- name: Check out repository code
uses: actions/checkout@v2
- name: Perform a Pester test from the command-line
shell: pwsh
run: Test-Path resultsfile.log | Should -Be $true
- name: Perform a Pester test from the Tests.ps1 file
shell: pwsh
run: |
Invoke-Pester Unit.Tests.ps1 -Passthru
-
shell: pwsh
– Configura o trabalho para usar o PowerShell ao executar os comandosrun
. -
run: Test-Path resultsfile.log
– Verifique se um arquivo chamadoresultsfile.log
está presente no diretório raiz do repositório. -
Should -Be $true
– Usa o Pester para definir um resultado esperado. Se o resultado for inesperado, GitHub Actions irá sinalizar isso como um teste falho. Por exemplo:
Invoke-Pester Unit.Tests.ps1 -Passthru
– Usa o Pester para executar testes definidos em um arquivo chamadoUnit.Tests.ps1
. Por exemplo, para executar o mesmo teste descrito acima, oUnit.Tests.ps1
conterá o seguinte:Describe "Check results file is present" { It "Check results file is present" { Test-Path resultsfile.log | Should -Be $true } }
Locais de módulos do PowerShell
A tabela abaixo descreve os locais para diversos módulos do PowerShell em cada executor hospedado em GitHub.
Ubuntu | macOS | Windows | |
---|---|---|---|
Módulos do sistema do PowerShell | /opt/microsoft/powershell/7/Modules/* | /usr/local/microsoft/powershell/7/Modules/* | C:\program files\powershell\7\Modules\* |
Módulos de complementos do PowerShell | /usr/local/share/powershell/Modules/* | /usr/local/share/powershell/Modules/* | C:\Modules\* |
Módulos instalados pelo usuário | /home/runner/.local/share/powershell/Modules/* | /Users/runner/.local/share/powershell/Modules/* | C:\Users\runneradmin\Documents\PowerShell\Modules\* |
Instalar dependências
Executores hospedados em GitHub têm PowerShell 7 e o Pester instalado. Use Install-Module
para instalar dependências adicionais da Galeria do PowerShell antes de compilar e testar seu código.
Observação: os pacotes pré-instalados (como o Pester) usados pelos executores hospedados no GitHub são atualizados regularmente e podem introduzir alterações significativas. Como resultado, recomendamos que você sempre especifique as versões de pacote necessárias usando Install-Module
com -MaximumVersion
.
Por exemplo, o seguinte trabalho instala os módulos SqlServer
e PSScriptAnalyzer
:
jobs:
install-dependencies:
name: Install dependencies
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install from PSGallery
shell: pwsh
run: |
Set-PSRepository PSGallery -InstallationPolicy Trusted
Install-Module SqlServer, PSScriptAnalyzer
Observação: por padrão, nenhum repositório é confiável pelo PowerShell. Ao instalar módulos da Galeria do PowerShell, você precisa definir explicitamente a política de instalação de PSGallery
como Trusted
.
Testar seu código
Você pode usar os mesmos comandos usados localmente para criar e testar seu código.
Usar PSScriptAnalyzer para código lint
O exemplo a seguir instala PSScriptAnalyzer
e o usa para fazer lint de todos os arquivos ps1
no repositório. Para obter mais informações, confira PSScriptAnalyzer no GitHub.
lint-with-PSScriptAnalyzer:
name: Install and run PSScriptAnalyzer
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install PSScriptAnalyzer module
shell: pwsh
run: |
Set-PSRepository PSGallery -InstallationPolicy Trusted
Install-Module PSScriptAnalyzer -ErrorAction Stop
- name: Lint with PSScriptAnalyzer
shell: pwsh
run: |
Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues
$errors = $issues.Where({$_.Severity -eq 'Error'})
$warnings = $issues.Where({$_.Severity -eq 'Warning'})
if ($errors) {
Write-Error "There were $($errors.Count) errors and $($warnings.Count) warnings total." -ErrorAction Stop
} else {
Write-Output "There were $($errors.Count) errors and $($warnings.Count) warnings total."
}
Empacotar dados do fluxo de trabalho como artefatos
Você pode fazer o upload de artefatos para visualização após a conclusão de um fluxo de trabalho. Por exemplo, é possível que você precise salvar os arquivos de registro, os despejos de núcleo, os resultados de teste ou capturas de tela. Para obter mais informações, confira "Como persistir dados de fluxo de trabalho usando artefatos".
O exemplo a seguir demonstra como usar a ação upload-artifact
para arquivar os resultados do teste recebidos de Invoke-Pester
. Para obter mais informações, confira a ação upload-artifact
.
name: Upload artifact from Ubuntu
on: [push]
jobs:
upload-pester-results:
name: Run Pester and upload results
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Test with Pester
shell: pwsh
run: Invoke-Pester Unit.Tests.ps1 -Passthru | Export-CliXml -Path Unit.Tests.xml
- name: Upload test results
uses: actions/upload-artifact@v2
with:
name: ubuntu-Unit-Tests
path: Unit.Tests.xml
if: ${{ always() }}
A função always()
configura o trabalho para continuar o processamento mesmo se houver falhas de teste. Para obter mais informações, confira "always".
Publicar na Galeria do PowerShell
Você pode configurar o seu fluxo de trabalho para publicar o seu módulo do PowerShell para a Galeria PowerShell quando o seu teste de passar. Você pode usar segredos para armazenar quaisquer tokens ou credenciais necessárias para publicar seu pacote. Para obter mais informações, confira "Como criar e usar segredos criptografados".
O seguinte exemplo cria um pacote e usa Publish-Module
para publicá-lo na Galeria do PowerShell:
name: Publish PowerShell Module
on:
release:
types: [created]
jobs:
publish-to-gallery:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build and publish
env:
NUGET_KEY: ${{ secrets.NUGET_KEY }}
shell: pwsh
run: |
./build.ps1 -Path /tmp/samplemodule
Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose