diff --git a/docs/CHANGELOG-v3.md b/docs/CHANGELOG-v3.md index e1ae3da644..f0b6b30e37 100644 --- a/docs/CHANGELOG-v3.md +++ b/docs/CHANGELOG-v3.md @@ -11,8 +11,6 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers **Experimental features**: -- Baseline groups allow you to use a friendly name to reference baselines. - See [baselines][6] for more information. - Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition. See [functions][3] for more information. - Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties. @@ -23,7 +21,6 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers [3]: expressions/functions.md [4]: expressions/sub-selectors.md [5]: creating-your-pipeline.md#processing-changed-files-only - [6]: concepts/baselines.md ## Unreleased diff --git a/docs/commands/PSRule/en-US/Assert-PSRule.md b/docs/commands/PSRule/en-US/Assert-PSRule.md index 58c8f0b87f..ddffdbaf47 100644 --- a/docs/commands/PSRule/en-US/Assert-PSRule.md +++ b/docs/commands/PSRule/en-US/Assert-PSRule.md @@ -162,39 +162,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Format - -Configures the input format for when a string is passed in as a target object. - -When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default. -Set this option to either `Yaml`, `Json`, `Markdown`, `PowerShellData` to have PSRule deserialize the object. - -When the `-InputPath` parameter is used with a file path or URL. -If the `Detect` format is used, the file extension will be used to automatically detect the format. -When `-InputPath` is not used, `Detect` is the same as `None`. - -When this option is set to `File` PSRule scans the path and subdirectories specified by `-InputPath`. -Files are treated as objects instead of being deserialized. -Additional, PSRule uses the file extension as the object type. -When files have no extension the whole file name is used. - -See `about_PSRule_Options` for details. - -This parameter takes precedence over the `Input.Format` option if set. - -```yaml -Type: InputFormat -Parameter Sets: (All) -Aliases: -Accepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect - -Required: False -Position: Named -Default value: Detect -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Baseline Specifies an explicit baseline by name to use for evaluating rules. diff --git a/docs/concepts/cli/run.md b/docs/concepts/cli/run.md index 3d180d1c44..91631c1dab 100644 --- a/docs/concepts/cli/run.md +++ b/docs/concepts/cli/run.md @@ -24,6 +24,17 @@ By default, this is the current working path. The name of one or more modules that contain rules or resources to use during a run. +### `--formats` + +Enables one or more formats by name to process files and deserialized objects. +All formats are disabled by default. + +For example, to enable JSON and YAML formats: + +```bash +--formats json yaml +``` + ### `--baseline` The name of a specific baseline to use. diff --git a/docs/creating-your-pipeline.md b/docs/creating-your-pipeline.md index b7c1f6f610..b1ddafc7ab 100644 --- a/docs/creating-your-pipeline.md +++ b/docs/creating-your-pipeline.md @@ -23,14 +23,15 @@ Within the root directory of your IaC repository: runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v4 - - # Analyze Azure resources using PSRule for Azure - - name: Analyze Azure template files - uses: microsoft/ps-rule@v2.9.0 - with: - modules: 'PSRule.Rules.Azure' + # Checkout the repository + - name: Checkout + uses: actions/checkout@v4 + + # Run PSRule + - name: Analyze with PSRule + uses: microsoft/ps-rule@v3.0.0 + with: + modules: PSRule.Rules.Azure ``` This will automatically install compatible versions of all dependencies. @@ -42,12 +43,14 @@ Within the root directory of your IaC repository: ```yaml steps: - # Analyze Azure resources using PSRule for Azure - - task: ps-rule-assert@2 - displayName: Analyze Azure template files - inputs: - inputType: repository - modules: 'PSRule.Rules.Azure' + # Checkout the repository + - checkout: self + + # Run PSRule + - task: ps-rule-assert@3 + displayName: Analyze with PSRule + inputs: + modules: PSRule.Rules.Azure ``` This will automatically install compatible versions of all dependencies. @@ -138,6 +141,9 @@ To prevent a rule executing you can either: Meaningful comments help during peer review within a Pull Request (PR). Also consider including a date if the exclusions or suppressions are temporary. + [3]: concepts/PSRule/en-US/about_PSRule_Options.md#ruleexclude + [4]: concepts/PSRule/en-US/about_PSRule_Options.md#suppression + [5]: concepts/PSRule/en-US/about_PSRule_SuppressionGroups.md [6]: addon-modules.md [7]: authoring/packaging-rules.md @@ -146,6 +152,7 @@ To prevent a rule executing you can either: :octicons-milestone-24: v2.5.0 ยท [:octicons-book-24: Docs][8] To only process files that have changed within a pull request, set the `Input.IgnoreUnchangedPath` option. +This option does not work with a shallow or detached checkout, full git history is required for comparison. === "GitHub Actions" @@ -161,18 +168,27 @@ To only process files that have changed within a pull request, set the `Input.Ig runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v4 - - # Analyze Azure resources using PSRule for Azure - - name: Analyze Azure template files - uses: microsoft/ps-rule@v2.9.0 - with: - modules: 'PSRule.Rules.Azure' - env: - PSRULE_INPUT_IGNOREUNCHANGEDPATH: true + # Checkout the repository + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # (1) + + # Run PSRule + - name: Analyze with PSRule + uses: microsoft/ps-rule@v3.0.0 + with: + modules: PSRule.Rules.Azure + env: + PSRULE_INPUT_IGNOREUNCHANGEDPATH: true # (2) ``` +
+ 1. Checkout the repository with full history. By default, GitHub Actions will only fetch the latest commit. + 2. Enable processing of changed files only. + +
+ === "Azure Pipelines" Update your Azure DevOps YAML pipeline by setting the `PSRULE_INPUT_IGNOREUNCHANGEDPATH` environment variable. @@ -180,16 +196,25 @@ To only process files that have changed within a pull request, set the `Input.Ig ```yaml title=".azure-pipelines/analyze-arm.yaml" steps: - # Analyze Azure resources using PSRule for Azure - - task: ps-rule-assert@2 - displayName: Analyze Azure template files - inputs: - inputType: repository - modules: 'PSRule.Rules.Azure' - env: - PSRULE_INPUT_IGNOREUNCHANGEDPATH: true + # Checkout the repository + - checkout: self + fetchDepth: 0 # (1) + + # Run PSRule + - task: ps-rule-assert@3 + displayName: Analyze with PSRule + inputs: + modules: PSRule.Rules.Azure + env: + PSRULE_INPUT_IGNOREUNCHANGEDPATH: true # (2) ``` +
+ 1. Checkout the repository with full history. By default, Azure Pipelines will only fetch the latest commit. + 2. Enable processing of changed files only. + +
+ === "Generic with PowerShell" Update your PowerShell command-line to include the `Input.IgnoreUnchangedPath` option. diff --git a/docs/updates/v3.0.md b/docs/updates/v3.0.md index 746702d5f8..545f760319 100644 --- a/docs/updates/v3.0.md +++ b/docs/updates/v3.0.md @@ -3,9 +3,9 @@ date: 2024-02-30 version: 3.0 --- -# vNEXT (v3.0) +# What's new in v3 -Welcome to the vNEXT release of PSRule. +Welcome to the v3 release of PSRule. There are many updates in this version that we hope you'll like, some of the key highlights include: - [Official CLI support](#official-cli-support) — A new CLI experience for PSRule. diff --git a/mkdocs.yml b/mkdocs.yml index bb54b088cd..0ae4bdc821 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,7 +79,7 @@ nav: - Related projects: related-projects.md - Support: support.md - Updates: - - vNEXT: updates/v3.0.md + - What's new in v3: updates/v3.0.md - Change log: CHANGELOG-v3.md - Deprecations: deprecations.md - Changes and versioning: versioning.md