Nota: Actualmente los ejecutores hospedados en GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.
Introducción
Esta guía te muestra cómo utilizar PowerShell para la IC. Describimos cómo utilizar Pester, instalar dependencias, probar tu módulo y publicarlo en la galería de PowerShell.
Los ejecutores hospedados en GitHub tienen un caché de herramientas con software pre-instalado, lo cual incluye a PowerShell y a Pester.
Para obtener una lista completa de software actualizado y las versiones preinstaladas de PowerShell y Pester, consulta "Utilizar los ejecutores hospedados en GitHub".
Requisitos previos
Deberías estar familiarizado con YAML y la sintaxis para las GitHub Actions. Para obtener más información, vea «Más información sobre las Acciones de GitHub».
Te recomendamos tener un entendimiento básico de PowerShell y de Pester. Para más información, consulte:
Utilizar ejecutores auto-hospedados en GitHub Enterprise Server
Cuando use acciones de configuración, (como actions/setup-LANGUAGE
) en GitHub Enterprise Server con ejecutores autohospedados, es posible que necesite configurar la caché de herramientas en los ejecutores que no tienen acceso a Internet. Para obtener más información, vea «Configurar el caché de la herramienta en ejecutores auto-hospedados sin acceso a internet».
Agregar un flujo de trabajo para Pester
Para automatizar tus pruebas con PowerShell y con Pester, puedes agregar un flujo de trabajo que se ejecute cada que se sube un cambio en tu repositorio. En el ejemplo siguiente, se usa Test-Path
para comprobar que existe un archivo con el nombre resultsfile.log
.
Este archivo de flujo de trabajo de ejemplo se debe agregar al directorio .github/workflows/
del repositorio:
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@v4
- 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 el trabajo para que use PowerShell al ejecutar los comandosrun
. -
run: Test-Path resultsfile.log
: comprueba si existe un archivo con el nombreresultsfile.log
en el directorio raíz del repositorio. -
Should -Be $true
: usa Pester para definir un resultado esperado. Si el resultado es inesperado, entonces GitHub Actions lo marca como una prueba fallida. Por ejemplo: -
Invoke-Pester Unit.Tests.ps1 -Passthru
: usa Pester para ejecutar pruebas definidas en un archivo denominadoUnit.Tests.ps1
. Por ejemplo, para realizar la misma prueba que se ha descrito antes,Unit.Tests.ps1
contendrá lo siguiente:Describe "Check results file is present" { It "Check results file is present" { Test-Path resultsfile.log | Should -Be $true } }
Ubicaciones de los módulos de PowerShell
En la siguiente tabla se describen las ubicaciones para varios módulos de PowerShell en cada ejecutor hospedado en GitHub.
Ubuntu | macOS | Windows | |
---|---|---|---|
Módulos de sistema de PowerShell | /opt/microsoft/powershell/7/Modules/* | /usr/local/microsoft/powershell/7/Modules/* | C:\program files\powershell\7\Modules\* |
Módulos de complementos de PowerShell | /usr/local/share/powershell/Modules/* | /usr/local/share/powershell/Modules/* | C:\Modules\* |
Módulos instalados por el usuario | /home/runner/.local/share/powershell/Modules/* | /Users/runner/.local/share/powershell/Modules/* | C:\Users\runneradmin\Documents\PowerShell\Modules\* |
Nota: En los ejecutores de Ubuntu, los módulos de Azure PowerShell se almacenan en /usr/share/
lugar de en la ubicación predeterminada de los módulos de complemento de PowerShell (es decir, /usr/local/share/powershell/Modules/
).
Instalación de dependencias
Los ejecutores hospedados en GitHub tienen PowerShell 7 y Pester instalados. Puede usar Install-Module
para instalar dependencias adicionales desde la Galería de PowerShell antes de compilar y probar el código.
Nota: Los paquetes preinstalados (Pester) que usan los ejecutores hospedados en GitHub se actualizan frecuentemente y pueden introducir cambios significativos. Como resultado, se recomienda especificar siempre las versiones de paquete necesarias mediante Install-Module
con -MaximumVersion
.
También puedes almacenar en caché las dependencias para acelerar el flujo de trabajo. Para más información, consulta "Almacenar en caché las dependencias para agilizar los flujos de trabajo".
Por ejemplo, el siguiente trabajo instala los módulos SqlServer
y PSScriptAnalyzer
:
jobs:
install-dependencies:
name: Install dependencies
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install from PSGallery
shell: pwsh
run: |
Set-PSRepository PSGallery -InstallationPolicy Trusted
Install-Module SqlServer, PSScriptAnalyzer
Nota: De forma predeterminada, PowerShell no confía en ningún repositorio. Al instalar módulos desde la Galería de PowerShell, debe establecer de forma explícita la directiva de instalación de PSGallery
en Trusted
.
Almacenar dependencias en caché
Puedes almacenar dependencias de PowerShell en caché con una clave única, lo que te permite restaurar las dependencias para flujos de trabajo futuros con la acción cache
. Para obtener más información, vea «Almacenar en caché las dependencias para agilizar los flujos de trabajo».
PowerShell guarda sus dependencias en caché en ubicaciones diferentes, dependiendo del sistema operativo del ejecutor. Por ejemplo, la ubicación path
que se usa en el siguiente ejemplo de Ubuntu será diferente a la de un sistema operativo Windows.
steps:
- uses: actions/checkout@v4
- name: Setup PowerShell module cache
id: cacher
uses: actions/cache@v3
with:
path: "~/.local/share/powershell/Modules"
key: ${{ runner.os }}-SqlServer-PSScriptAnalyzer
- name: Install required PowerShell modules
if: steps.cacher.outputs.cache-hit != 'true'
shell: pwsh
run: |
Set-PSRepository PSGallery -InstallationPolicy Trusted
Install-Module SqlServer, PSScriptAnalyzer -ErrorAction Stop
Probar el código
Puedes usar los mismos comandos que usas de forma local para construir y probar tu código.
Utilizar PSScriptAnalyzer para limpiar el código
En el ejemplo siguiente se instala PSScriptAnalyzer
y se usa para el lint de todos los archivos ps1
del repositorio. Para más información, vea PSScriptAnalyzer en GitHub.
lint-with-PSScriptAnalyzer:
name: Install and run PSScriptAnalyzer
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- 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."
}
Empaquetar datos de flujo de trabajo como artefactos
Puedes cargar artefactos para ver después de que se complete un flujo de trabajo. Por ejemplo, es posible que debas guardar los archivos de registro, los vaciados de memoria, los resultados de las pruebas o las capturas de pantalla. Para obtener más información, vea «Almacenar los datos de los flujos de trabajo como artefactos».
En el ejemplo siguiente se muestra cómo puede usar la upload-artifact
acción para archivar los resultados de la prueba recibidos de Invoke-Pester
. Para más información, vea la acción 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@v4
- 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@v3
with:
name: ubuntu-Unit-Tests
path: Unit.Tests.xml
if: ${{ always() }}
La función always()
configura el trabajo para que el procesamiento continúe aunque se produzcan fallos en las pruebas. Para obtener más información, vea «Contextos».
Publicar en la galería de PowerShell
Puedes configurar tu flujo de trabajo para que publique tu módulo de PowerShell en la galería de PowerShell cuando pasen tus pruebas de IC. Puedes utilizar los secretos para almacenar cualquier token o credencial que se necesiten para publicar tu paquete. Para obtener más información, vea «Uso de secretos en Acciones de GitHub».
En el ejemplo siguiente se crea un paquete y se usa Publish-Module
para publicarlo en la Galería de PowerShell:
name: Publish PowerShell Module
on:
release:
types: [created]
jobs:
publish-to-gallery:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- 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