Update task docs and parameters (#6)

This commit is contained in:
Bernie White 2020-04-14 18:30:11 +10:00 коммит произвёл GitHub
Родитель a9966e7ac9
Коммит d2c1559f6f
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
8 изменённых файлов: 172 добавлений и 151 удалений

Просмотреть файл

@ -16,90 +16,67 @@ The PSRule extension includes the following tasks for Azure Pipelines:
Name | Friendly name | Description | Reference
---- | ------------- | ----------- | ---------
`ps-rule-assert` | PSRule analysis | Run analysis with PSRule. | [reference][ps-rule-assert]
`ps-rule-install` | Install a PSRule module | Install PowerShell modules containing rules. | [reference][ps-rule-install]
`ps-rule-install` | Install PSRule module | Install a PowerShell module containing rules. | [reference][ps-rule-install]
To add these tasks, use the name for YAML pipelines or friendly name of classic pipelines.
### Pre-installing the PSRule module
### Installing PSRule extension
A point in time release of PSRule is distributed with this extension.
To use pre-release versions or a newer version of PSRule use PowerShell to pre-install using:
To use PSRule within Azure DevOps Services, install the [extension] from the [Visual Studio Marketplace][extension].
For detailed instructions see [Install extensions][extension-install].
```powershell
Install-Module -Name PSRule -Scope CurrentUser -Force;
```
If you don't have permissions to install extensions within your Azure DevOps organization,
you can request it to be installed by an admin instead.
Using YAML pipelines:
### Using within YAML pipelines
To use these tasks within YAML pipelines:
- Install rule modules with the `ps-rule-install` task (optional).
- Run analysis one or more times with the `ps-rule-assert` task.
- Publish analysis results with the [Publish Test Results](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/test/publish-test-results?view=azure-devops&tabs=yaml) builtin task.
For example:
```yaml
steps:
- powershell: Install-Module -Name PSRule -Scope CurrentUser -Force;
```
### Using rules modules from PowerShell Gallery
To use PSRule modules, install them before using the `ps-rule-assert` task.
To install modules from the PowerShell Gallery, use the `ps-rule-install` task.
Using YAML pipelines:
```yaml
steps:
# Install the PSRule.Rules.Azure module
# Install PSRule.Rules.Azure from the PowerShell Gallery
- task: ps-rule-install@0
inputs:
module: PSRule.Rules.Azure
```
module: PSRule.Rules.Azure # Install PSRule.Rules.Azure from the PowerShell Gallery.
latest: false # Only install the module if not already installed.
prerelease: false # Install stable versions only.
### Using rules from Azure Artifacts
More to come.
### Assert repository structure
Using YAML pipelines:
```yaml
steps:
# Run analysis from JSON files using the `PSRule.Rules.Azure` module and custom rules from `.ps-rule/`.
- task: ps-rule-assert@0
inputs:
source: '.ps-rule/'
inputType: repository
```
### Assert an input path
Using YAML pipelines:
```yaml
steps:
- task: ps-rule-assert@0
inputs:
source: '.ps-rule/'
inputType: inputPath
inputPath: 'out/'
```
inputPath: 'out/*.json' # Read objects from JSON files in 'out/'.
modules: 'PSRule.Rules.Azure' # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.
source: '.ps-rule/' # Additionally, analyze object using custom rules from '.ps-rule/'.
outputType: NUnit3 # Save results to an NUnit report
outputPath: reports/ps-rule-results.xml # Write NUnit report to 'reports/ps-rule-results.xml'.
```yaml
steps:
- task: ps-rule-assert@0
# Publish NUnit report as test results
- task: PublishTestResults@2
displayName: 'Publish PSRule results'
inputs:
source: '.ps-rule/'
inputType: repository
outputType: NUnit3
outputPath: reports/ps-rule-loopback.xml
testRunTitle: 'PSRule' # The title to use for the test run.
testRunner: NUnit # Import report using the NUnit format.
testResultsFiles: 'reports/ps-rule-results.xml' # The previously saved NUnit report.
```
## Changes and versioning
Extensions and tasks in this repository will use the [semantic versioning](http://semver.org/) model to declare breaking changes from v1.0.0.
Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments.
For a list of module changes please see the [change log](CHANGELOG.md).
For a list of module changes please see the [change log].
## Contributing
This project welcomes contributions and suggestions.
If you are ready to contribute, please visit the [contribution guide](CONTRIBUTING.md).
If you are ready to contribute, please visit the [contribution guide].
## Code of Conduct
@ -113,10 +90,14 @@ or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any addi
## License
This project is [licensed under the MIT License](LICENSE).
This project is [licensed under the MIT License][license].
[issues]: https://github.com/BernieWhite/PSRule-pipelines/issues
[ci-badge]: https://dev.azure.com/bewhite/PSRule-pipelines/_apis/build/status/PSRule-pipelines-CI?branchName=master
[extension]: https://marketplace.visualstudio.com/items?itemName=bewhite.ps-rule
[extension-install]: https://docs.microsoft.com/en-us/azure/devops/marketplace/install-extension?view=azure-devops&tabs=browser
[ps-rule-assert]: docs/tasks.md#ps-rule-assert
[ps-rule-install]: docs/tasks.md#ps-rule-install
[contribution guide]: https://github.com/BernieWhite/PSRule-pipelines/blob/master/CONTRIBUTING.md
[change log]: https://github.com/BernieWhite/PSRule-pipelines/blob/master/CHANGELOG.md
[license]: https://github.com/BernieWhite/PSRule-pipelines/blob/master/LICENSE

Просмотреть файл

@ -7,44 +7,106 @@ The following pipeline tasks are included in this extension.
Use this task to install rule modules and their dependencies.
Modules will be installed to the current user scope.
### Syntax
```yaml
steps:
- task: ps-rule-install@0
inputs:
module: PSRule.Rules.Azure # The name of a rule module to install.
latest: false # Optional. Determine if the installed module is updated to the latest version.
prerelease: false # Optional. Determine if a pre-release module version is installed.
path: '' # Optional. The current working path for the task to execute from.
module: string # Required. The name of a rule module to install.
latest: boolean # Optional. Determine if the installed module is updated to the latest version.
prerelease: boolean # Optional. Determine if a pre-release module version is installed.
```
Inputs:
- **module**: The name of a rule module to install.
The module will be installed from the PowerShell Gallery.
For example: _PSRule.Rules.Azure_
- **latest**: Determine if the installed module is updated to the latest version.
- **prerelease**: Determine if a pre-release module version is installed.
### Example: Installing a rule module
Install the latest stable version of `PSRule.Rules.Azure` from the PowerShell Gallery if not already installed.
```yaml
steps:
- task: ps-rule-install@0
inputs:
module: PSRule.Rules.Azure # Install PSRule.Rules.Azure from the PowerShell Gallery.
latest: false # Only install the module if not already installed.
prerelease: false # Install stable versions only.
```
## ps-rule-assert
Perform analysis and assert PSRule conditions.
Analysis can be perform from input files or the repository structure.
```yaml
steps:
- task: ps-rule-assert@0
inputs:
source: '.ps-rule/'
inputType: inputPath
inputPath: 'out/'
```
### Syntax
```yaml
steps:
- task: ps-rule-assert@0
inputs:
source: '.ps-rule/'
inputType: repository
outputType: NUnit3
outputPath: reports/ps-rule-loopback.xml
inputType: repository, inputPath # Required. Determines the type of input to use for PSRule.
inputPath: string # Required. The path PSRule will look for files to validate.
modules: string # Optional. A comma separated list of modules to use for analysis.
source: string # Optional. An path containing rules to use for analysis.
outputFormat: None, Yaml, Json, NUnit3, Csv # Optional. The format to use when writing results to disk.
outputPath: string # Optional. The file path to write results to.
path: string # Optional. The working directory PSRule is run from.
```
- **inputType**: Determines the type of input to use for PSRule.
Either `repository` or `inputPath`.
When `inputType: inputPath` is used, supported file formats within `inputPath` will be read as objects.
When `inputType: repository` is used, the structure of the repository will be analyzed instead.
- **inputPath**: Set the `inputPath` to determine where PSRule will look for input files.
When `inputType: inputPath` this is binds to the [-InputPath](https://microsoft.github.io/PSRule/commands/PSRule/en-US/Assert-PSRule.html#-inputpath) parameter.
When `inputType: repository` this will be the repository root that PSRule analyzes.
- **modules**: A comma separated list of modules to use for analysis.
Install PSRule modules using the `ps-rule-install` task.
If the modules have not been installed,
the latest stable version will be installed from the PowerShell Gallery automatically.
For example: _PSRule.Rules.Azure,PSRule.Rules.Kubernetes_
- **source**: An path containing rules to use for analysis.
Use this option to include rules not installed as a PowerShell module.
This binds to the [-Path](https://microsoft.github.io/PSRule/commands/PSRule/en-US/Assert-PSRule.html#-path) parameter.
- **outputFormat**: Output results can be written to disk in addition to the default output.
Use this option to determine the format to write results.
By default, results are not written to disk.
This binds to the [-OutputFormat](https://microsoft.github.io/PSRule/commands/PSRule/en-US/Assert-PSRule.html#-outputformat) parameter.
- **outputPath**: The file path to write results to.
This binds to the [-OutputPath](https://microsoft.github.io/PSRule/commands/PSRule/en-US/Assert-PSRule.html#-outputpath) parameter.
- **path**: The working directory PSRule is run from.
Options specified in `ps-rule.yaml` from this directory will be used unless overridden by inputs.
### Example: Run analysis from input files
Run analysis from JSON files using the `PSRule.Rules.Azure` module and custom rules from `.ps-rule/`.
```yaml
steps:
- task: ps-rule-assert@0
inputs:
inputType: inputPath
inputPath: 'out/*.json' # Read objects from JSON files in 'out/'.
modules: 'PSRule.Rules.Azure' # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.
source: '.ps-rule/' # Additionally, analyze object using custom rules from '.ps-rule/'.
```
### Example: Run analysis of repository structure
Run analysis of the repository structure using the `PSRule.Rules.Azure` module.
Results are outputted to a NUnit format that can be published using the publish results task.
```yaml
steps:
- task: ps-rule-assert@0
inputs:
inputType: repository # Analyze repository structure.
inputPath: $(BUILD_SOURCESDIRECTORY) # Read repository structure from the default source path.
modules: 'PSRule.Rules.Azure' # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.
outputType: NUnit3 # Save results to an NUnit report
outputPath: reports/ps-rule-results.xml # Write NUnit report to 'reports/ps-rule-results.xml'.
```

Просмотреть файл

@ -18,61 +18,55 @@ The PSRule extension includes the following tasks for Azure Pipelines:
Name | Friendly name | Description | Reference
---- | ------------- | ----------- | ---------
`ps-rule-assert` | PSRule analysis | Run analysis with PSRule. | [reference][ps-rule-assert]
`ps-rule-install` | Install PSRule module | Install PowerShell modules containing rules. | [reference][ps-rule-install]
`ps-rule-install` | Install PSRule module | Install a PowerShell module containing rules. | [reference][ps-rule-install]
To add these tasks, use the name for YAML pipelines or friendly name of classic pipelines.
### Using rules modules from PowerShell Gallery
### Installing PSRule extension
To use rules modules, install them before using the `ps-rule-assert` task.
To install modules automatically from the PowerShell Gallery, use the `ps-rule-install` task.
To use PSRule within Azure DevOps Services, install the [extension] from the [Visual Studio Marketplace][extension].
For detailed instructions see [Install extensions][extension-install].
Using YAML pipelines:
If you don't have permissions to install extensions within your Azure DevOps organization,
you can request it to be installed by an admin instead.
### Using within YAML pipelines
To use these tasks within YAML pipelines:
- Install rule modules with the `ps-rule-install` task (optional).
- Run analysis one or more times with the `ps-rule-assert` task.
- Publish analysis results with the [Publish Test Results](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/test/publish-test-results?view=azure-devops&tabs=yaml) builtin task.
For example:
```yaml
steps:
# Install PSRule.Rules.Azure from the PowerShell Gallery
- task: ps-rule-install@0
inputs:
modules: PSRule.Rules.Azure
```
module: PSRule.Rules.Azure # Install PSRule.Rules.Azure from the PowerShell Gallery.
latest: false # Only install the module if not already installed.
prerelease: false # Install stable versions only.
### Using rules from Azure Artifacts
More to come.
### Assert repository structure
Using YAML pipelines:
```yaml
steps:
# Run analysis from JSON files using the `PSRule.Rules.Azure` module and custom rules from `.ps-rule/`.
- task: ps-rule-assert@0
inputs:
source: '.ps-rule/'
inputType: repository
```
### Assert an input path
Using YAML pipelines:
```yaml
steps:
- task: ps-rule-assert@0
inputs:
source: '.ps-rule/'
inputType: inputPath
inputPath: 'out/'
```
inputPath: 'out/*.json' # Read objects from JSON files in 'out/'.
modules: 'PSRule.Rules.Azure' # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.
source: '.ps-rule/' # Additionally, analyze object using custom rules from '.ps-rule/'.
outputType: NUnit3 # Save results to an NUnit report
outputPath: reports/ps-rule-results.xml # Write NUnit report to 'reports/ps-rule-results.xml'.
```yaml
steps:
- task: ps-rule-assert@0
# Publish NUnit report as test results
- task: PublishTestResults@2
displayName: 'Publish PSRule results'
inputs:
source: '.ps-rule/'
inputType: repository
outputType: NUnit3
outputPath: reports/ps-rule-loopback.xml
testRunTitle: 'PSRule' # The title to use for the test run.
testRunner: NUnit # Import report using the NUnit format.
testResultsFiles: 'reports/ps-rule-results.xml' # The previously saved NUnit report.
```
## Changes and versioning
@ -103,6 +97,7 @@ This project is [licensed under the MIT License][license].
[issues]: https://github.com/BernieWhite/PSRule-pipelines/issues
[ci-badge]: https://dev.azure.com/bewhite/PSRule-pipelines/_apis/build/status/PSRule-pipelines-CI?branchName=master
[extension]: https://marketplace.visualstudio.com/items?itemName=bewhite.ps-rule
[extension-install]: https://docs.microsoft.com/en-us/azure/devops/marketplace/install-extension?view=azure-devops&tabs=browser
[ps-rule-assert]: https://github.com/BernieWhite/PSRule-pipelines/blob/master/docs/tasks.md#ps-rule-assert
[ps-rule-install]: https://github.com/BernieWhite/PSRule-pipelines/blob/master/docs/tasks.md#ps-rule-install
[contribution guide]: https://github.com/BernieWhite/PSRule-pipelines/blob/master/CONTRIBUTING.md

Просмотреть файл

@ -46,6 +46,9 @@ if ($Null -eq $Path) {
if ([String]::IsNullOrEmpty($Path)) {
$Path = $PWD;
}
if ($Null -eq $InputPath) {
$InputPath = $Path;
}
if ([String]::IsNullOrEmpty($Source)) {
$Source = Join-Path -Path $Path -ChildPath '.ps-rule/';
}
@ -146,8 +149,8 @@ try {
if ($InputType -eq 'repository') {
$items = New-Object -TypeName System.Collections.ArrayList;
WriteDebug 'Running ''Assert-PSRule'' with repository as input.';
$Null = $items.Add((Get-Item -Path $Path));
$Null = $items.AddRange((Get-ChildItem -Path $Path -File -Recurse));
$Null = $items.Add((Get-Item -Path $InputPath));
$Null = $items.AddRange((Get-ChildItem -Path $InputPath -File -Recurse));
Write-Host '';
Write-Host '---';
$items.ToArray() | Assert-PSRule @invokeParams;

Просмотреть файл

@ -16,16 +16,12 @@ async function run() {
// Get inputs
let input_path: string = task.getPathInput('path', /*required*/ true, /*check*/ true);
let input_inputType: string = task.getInput('inputType', /*required*/ true);
let input_inputPath: string;
let input_inputPath: string = task.getInput('inputPath', /*required*/ true);
let input_source: string = task.getPathInput('source', /*required*/ false, /*check*/ false);
let input_modules: string = task.getInput('modules', /*required*/ false);
let input_outputFormat: string = task.getPathInput('outputFormat', /*required*/ false, /*check*/ false) || 'None';
let input_outputPath: string = task.getPathInput('outputPath', /*required*/ false, /*check*/ false);
if (input_inputType.toUpperCase() === 'INPUTPATH') {
input_inputPath = task.getInput('inputPath', /*required*/ true);
}
// Write bootstrap commands to a temporary script file
let contents: string[] = [];
@ -35,10 +31,7 @@ async function run() {
contents.push(`Import-Module $sdkPath -ArgumentList @{ NonInteractive = 'true' }`);
// Prepare parameters
contents.push(`$scriptParams = @{ Path = '${input_path}'; InputType = '${input_inputType}' };`);
if (input_inputPath !== undefined) {
contents.push(`$scriptParams['InputPath'] = '${input_inputPath}'`);
}
contents.push(`$scriptParams = @{ Path = '${input_path}'; InputType = '${input_inputType}' }; InputPath = '${input_inputPath}' };`);
if (input_source !== undefined) {
contents.push(`$scriptParams['Source'] = '${input_source}'`);
}

Просмотреть файл

@ -22,7 +22,7 @@
"Patch": 1
},
"preview": true,
"releaseNotes": "",
"releaseNotes": "[See change log](https://github.com/BernieWhite/PSRule-pipelines/blob/master/CHANGELOG.md)",
"groups": [
{
"name": "advanced",
@ -39,7 +39,7 @@
"groupName": "advanced",
"defaultValue": "",
"required": false,
"helpMarkDown": "Working directory where PSRule is run from."
"helpMarkDown": "The working directory PSRule is run from."
},
{
"name": "inputType",
@ -57,10 +57,9 @@
"name": "inputPath",
"type": "filePath",
"label": "Input file(s)",
"defaultValue": "*.json",
"required": false,
"helpMarkDown": "One or more input files containing objects for PSRule to validate. This binds to the `-InputPath` parameter. File type is detected based on file extension.",
"visibleRule": "inputType = inputPath"
"defaultValue": "",
"required": true,
"helpMarkDown": "The path PSRule will look for files to validate."
},
{
"name": "source",
@ -68,7 +67,7 @@
"label": "Source path",
"defaultValue": ".ps-rule/",
"required": false,
"helpMarkDown": "Path to the rule source location."
"helpMarkDown": "An path containing rules to use for analysis."
},
{
"name": "modules",
@ -103,7 +102,7 @@
"visibleRule": "outputFormat != None"
}
],
"instanceNameFormat": "PSRule analysis",
"instanceNameFormat": "Run PSRule analysis",
"execution": {
"PowerShell3": {
"target": "powershell.ps1",

Просмотреть файл

@ -14,8 +14,7 @@ async function run() {
task.setResourcePath(path.join(__dirname, 'task.json'));
// Get inputs
let input_path: string = task.getPathInput('path', /*required*/ true, /*check*/ true);
let input_module: string = task.getInput('module', /*required*/ false);
let input_module: string = task.getInput('module', /*required*/ true);
let input_latest: boolean = task.getBoolInput('latest', /*required*/ true);
let input_prerelease: boolean = task.getBoolInput('prerelease', /*required*/ true);
@ -63,7 +62,6 @@ async function run() {
.arg('-Command')
.arg(`. '${filePath.replace("'", "''")}'`);
const options = <runner.IExecOptions>{
cwd: input_path,
failOnStdErr: false,
errStream: process.stdout,
outStream: process.stdout,

Просмотреть файл

@ -2,7 +2,7 @@
"$schema": "https://raw.githubusercontent.com/microsoft/azure-pipelines-task-lib/master/tasks.schema.json",
"id": "0848dd65-bc06-4882-ae15-e2609d7fab0d",
"name": "ps-rule-install",
"friendlyName": "Install a PSRule module",
"friendlyName": "Install PSRule module",
"description": "Install a PowerShell module containing rules.",
"helpUrl": "https://github.com/BernieWhite/PSRule-pipelines/blob/master/docs/tasks.md#ps-rule-install",
"helpMarkDown": "[Learn more about this task](https://github.com/BernieWhite/PSRule-pipelines/blob/master/docs/tasks.md#ps-rule-install)",
@ -22,7 +22,7 @@
"Patch": 1
},
"preview": true,
"releaseNotes": "",
"releaseNotes": "[See change log](https://github.com/BernieWhite/PSRule-pipelines/blob/master/CHANGELOG.md)",
"groups": [
{
"name": "advanced",
@ -32,22 +32,12 @@
],
"minimumAgentVersion": "2.115.0",
"inputs": [
{
"name": "path",
"type": "filePath",
"label": "Working directory",
"groupName": "advanced",
"defaultValue": "",
"required": false,
"helpMarkDown": "Working directory where PSRule is run from."
},
{
"name": "module",
"type": "string",
"label": "Module",
"required": false,
"defaultValue": "",
"helpMarkDown": "The name of a PSRule module to install."
"required": true,
"helpMarkDown": "The name of a PSRule module to install from the PowerShell Gallery."
},
{
"name": "latest",
@ -68,7 +58,7 @@
"groupName": "advanced"
}
],
"instanceNameFormat": "Install PSRule module $(modules)",
"instanceNameFormat": "Install $(module)",
"execution": {
"PowerShell3": {
"target": "powershell.ps1",