Skip to content

Commit db490dd

Browse files
BernieWhiteBernieWhite
authored
Refactoring for splitting runs #2611 (#2695)
1 parent cfc6575 commit db490dd

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+1832
-810
lines changed

‎.github/workflows/build.yaml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@ env:
2727
permissions: {}
2828

2929
jobs:
30-
build:
31-
name: Build
30+
build_module:
31+
name: Build module
3232
runs-on: ubuntu-latest
3333
permissions:
3434
contents: read
@@ -76,10 +76,10 @@ jobs:
7676
retention-days: 3
7777
if-no-files-found: error
7878

79-
test:
80-
name: 🧪 Test (${{ matrix.rid }}-${{ matrix.shell }})
79+
test_module:
80+
name: 🧪 Test module (${{ matrix.rid }}-${{ matrix.shell }})
8181
runs-on: ${{ matrix.os }}
82-
needs: build
82+
needs: build_module
8383
permissions:
8484
contents: read
8585

‎README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -339,6 +339,9 @@ The following conceptual topics exist in the `PSRule` module:
339339
- [Rule.IncludeLocal](https://aka.ms/ps-rule/options#ruleincludelocal)
340340
- [Rule.Exclude](https://aka.ms/ps-rule/options#ruleexclude)
341341
- [Rule.Tag](https://aka.ms/ps-rule/options#ruletag)
342+
- [Run.Category](https://aka.ms/ps-rule/options##runcategory)
343+
- [Run.Description](https://aka.ms/ps-rule/options##rundescription)
344+
- [Run.Instance](https://aka.ms/ps-rule/options##runinstance)
342345
- [Suppression](https://aka.ms/ps-rule/options#suppression)
343346
- [Rules](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Rules/)
344347
- [Selectors](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Selectors/)

‎docs/concepts/PSRule/en-US/about_PSRule_Options.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,9 @@ The following workspace options are available for use:
6464
- [Repository.BaseRef](#repositorybaseref)
6565
- [Repository.Url](#repositoryurl)
6666
- [Requires](#requires)
67+
- [Run.Category](#runcategory)
68+
- [Run.Description](#rundescription)
69+
- [Run.Instance](#runinstance)
6770
- [Suppression](#suppression)
6871

6972
Additionally the following baseline options can be included:
@@ -3442,6 +3445,95 @@ rule:
34423445

34433446
In the example above, rules must have a tag of `severity` set to either `Critical` or `Warning` to be included.
34443447

3448+
### Run.Category
3449+
3450+
<!-- module:version 3.0.0 -->
3451+
3452+
Configures the run category that is used as an identifier for output results.
3453+
By default, the run category is set to `PSRule`.
3454+
3455+
This option can be specified using:
3456+
3457+
```powershell
3458+
# PowerShell: Using the Run.Category hashtable key
3459+
$option = New-PSRuleOption -Option @{ 'Run.Category' = 'Custom run' };
3460+
```
3461+
3462+
```yaml
3463+
# YAML: Using the run/category property
3464+
run:
3465+
category: Custom run
3466+
```
3467+
3468+
```bash
3469+
# Bash: Using environment variable
3470+
export PSRULE_RUN_CATEOGRY='Custom run'
3471+
```
3472+
3473+
```yaml
3474+
# GitHub Actions: Using environment variable
3475+
env:
3476+
PSRULE_RUN_CATEOGRY: 'Custom run'
3477+
```
3478+
3479+
```yaml
3480+
# Azure Pipelines: Using environment variable
3481+
variables:
3482+
- name: PSRULE_RUN_CATEOGRY
3483+
value: 'Custom run'
3484+
```
3485+
3486+
### Run.Description
3487+
3488+
<!-- module:version 3.0.0 -->
3489+
3490+
Configure the run description that is displayed in output.
3491+
By default, the run description is not set.
3492+
3493+
This option can be specified using:
3494+
3495+
```powershell
3496+
# PowerShell: Using the Run.Description hashtable key
3497+
$option = New-PSRuleOption -Option @{ 'Run.Description' = 'Custom run description.' };
3498+
```
3499+
3500+
```yaml
3501+
# YAML: Using the run/description property
3502+
run:
3503+
description: Custom run description.
3504+
```
3505+
3506+
```bash
3507+
# Bash: Using environment variable
3508+
export PSRULE_RUN_DESCRIPTION='Custom run description.'
3509+
```
3510+
3511+
```yaml
3512+
# GitHub Actions: Using environment variable
3513+
env:
3514+
PSRULE_RUN_DESCRIPTION: 'Custom run description.'
3515+
```
3516+
3517+
```yaml
3518+
# Azure Pipelines: Using environment variable
3519+
variables:
3520+
- name: PSRULE_RUN_DESCRIPTION
3521+
value: 'Custom run description.'
3522+
```
3523+
3524+
### Run.Instance
3525+
3526+
<!-- module:version 3.0.0 -->
3527+
3528+
An unique identifier for the current parent environment instance that is displayed in output as a component of the run ID.
3529+
This is automatically set by PSRule when running in a GitHub Actions or Azure Pipeline pipeline.
3530+
Alternatively, this option can be set using environment variables.
3531+
3532+
```bash
3533+
# Bash: Using environment variable
3534+
export PSRULE_RUN_INSTANCE='12345678'
3535+
```
3536+
34453537
### Suppression
34463538

34473539
In certain circumstances it may be necessary to exclude or suppress rules from processing objects that are in a known failed state.

‎docs/concepts/runs.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: About runs
3+
description: This article describes how PSRule organizes and manages each logical run.
4+
module: 3.0.0
5+
---
6+
7+
# Runs
8+
9+
This article describes how PSRule organizes and manages each logical run.
10+
11+
When PSRule is executed one or more runs will be automatically created.
12+
13+
## Configuring runs
14+
15+
PSRule allows the following options to be configured that affects runs:
16+
17+
- [Execution.Category]
18+
- [Execution.Description]

‎docs/concepts/sarif-format.md

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,75 @@ When running PSRule executed a run will be generated in `runs` containing detail
1212

1313
## Invocation
1414

15-
The `invocation` property reports runtime information about how the run started.
15+
The `invocations` property reports runtime information about how the run started.
1616

1717
### RuleConfigurationOverrides
1818

1919
When a rule has been overridden in configuration this invocation property will contain any level overrides.
20+
21+
## Examples
22+
23+
### Successful result
24+
25+
```json
26+
{
27+
"$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json",
28+
"version": "2.1.0",
29+
"runs": [
30+
{
31+
"tool": {
32+
"driver": {
33+
"guid": "0130215d-58eb-4887-b6fa-31ed02500569",
34+
"name": "PSRule",
35+
"organization": "Microsoft Corporation",
36+
"semanticVersion": "2.9.0",
37+
"informationUri": "https://aka.ms/ps-rule"
38+
},
39+
"extensions": [
40+
{
41+
"guid": "7bfb5234-1648-4e52-956c-42f303d416cb",
42+
"name": "PSRule.Rules.MSFT.OSS",
43+
"organization": "Microsoft Corporation",
44+
"version": "1.1.0",
45+
"informationUri": "https://github.com/microsoft/PSRule.Rules.MSFT.OSS",
46+
"associatedComponent": {
47+
"name": "PSRule"
48+
}
49+
}
50+
]
51+
},
52+
"automationDetails": {
53+
"id": "CI repository scan/workspace/1",
54+
"description": {
55+
"text": "An analysis scan that checks repository files."
56+
},
57+
"correlationGuid": "00000000-0000-0000-0000-000000000000"
58+
},
59+
"invocations": [
60+
{
61+
"executionSuccessful": true
62+
}
63+
],
64+
"versionControlProvenance": [
65+
{
66+
"repositoryUri": "https://github.com/microsoft/PSRule",
67+
"revisionId": "2a3671213e5768aad6af7f132e418d1a4368a3c5",
68+
"branch": "main",
69+
"mappedTo": {
70+
"uriBaseId": "REPO_ROOT"
71+
}
72+
}
73+
],
74+
"originalUriBaseIds": {
75+
"REPO_ROOT": {
76+
"description": {
77+
"text": "The directory into which the repo was cloned."
78+
}
79+
}
80+
},
81+
"results": [],
82+
"columnKind": "utf16CodeUnits"
83+
}
84+
]
85+
}
86+
```

‎docs/examples/baseline/Baseline.Rule.yaml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Copyright (c) Microsoft Corporation.
2+
# Licensed under the MIT License.
3+
4+
---
5+
# Synopsis: An example baseline.
6+
apiVersion: github.com/microsoft/PSRule/v1
7+
kind: Baseline
8+
metadata:
9+
name: Baseline.Rule
10+
displayName: Baseline.Rule
11+
description: An example baseline.
12+
spec: {}

‎docs/examples/sarif/basic-1.sarif

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{
2+
"$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json",
3+
"version": "2.1.0",
4+
"runs": [
5+
{
6+
"automationDetails": {
7+
"id": "CI repository scan/workspace/1",
8+
"description": {
9+
"text": "An analysis scan that checks repository files."
10+
},
11+
"correlationGuid": "00000000-0000-0000-0000-000000000000"
12+
},
13+
"tool": {
14+
"driver": {
15+
"guid": "0130215d-58eb-4887-b6fa-31ed02500569",
16+
"name": "PSRule",
17+
"organization": "Microsoft Corporation",
18+
"semanticVersion": "2.9.0",
19+
"informationUri": "https://aka.ms/ps-rule"
20+
},
21+
"extensions": [
22+
{
23+
"guid": "7bfb5234-1648-4e52-956c-42f303d416cb",
24+
"name": "PSRule.Rules.MSFT.OSS",
25+
"organization": "Microsoft Corporation",
26+
"version": "1.1.0",
27+
"informationUri": "https://github.com/microsoft/PSRule.Rules.MSFT.OSS",
28+
"associatedComponent": {
29+
"name": "PSRule"
30+
}
31+
}
32+
]
33+
},
34+
"invocations": [
35+
{
36+
"executionSuccessful": true
37+
}
38+
],
39+
"versionControlProvenance": [
40+
{
41+
"repositoryUri": "https://github.com/microsoft/PSRule",
42+
"revisionId": "2a3671213e5768aad6af7f132e418d1a4368a3c5",
43+
"branch": "main",
44+
"mappedTo": {
45+
"uriBaseId": "REPO_ROOT"
46+
}
47+
}
48+
],
49+
"originalUriBaseIds": {
50+
"REPO_ROOT": {
51+
"description": {
52+
"text": "The directory into which the repo was cloned."
53+
}
54+
}
55+
},
56+
"results": [],
57+
"columnKind": "utf16CodeUnits"
58+
}
59+
]
60+
}

‎ps-rule-ci.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ repository:
99
url: https://github.com/microsoft/PSRule
1010
baseRef: main
1111

12+
run:
13+
category: CI repository scan
14+
description: An analysis scan that checks repository files aligned to expected format requirements.
15+
1216
output:
1317
culture:
1418
- en-US

‎ps-rule.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ repository:
99
url: https://github.com/microsoft/PSRule
1010
baseRef: main
1111

12+
run:
13+
category: Scan for tests
14+
description: This is used for unit testing and should not be used directly.
15+
1216
output:
1317
culture:
1418
- en-US

‎schemas/PSRule-options.schema.json

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -784,6 +784,29 @@
784784
},
785785
"additionalProperties": false
786786
},
787+
"run-option": {
788+
"type": "object",
789+
"title": "Run",
790+
"description": "Configures run options.",
791+
"markdownDescription": "Configures run options.",
792+
"properties": {
793+
"category": {
794+
"type": "string",
795+
"title": "Category",
796+
"description": "Configures the run category that is used as an identifier for output results. By default, the category is PSRule.",
797+
"markdownDescription": "Configures the run category that is used as an identifier for output results. By default, the category is `PSRule`.\n\n[See help](https://microsoft.github.io/PSRule/v3/concepts/PSRule/en-US/about_PSRule_Options/#executioncategory)",
798+
"default": "PSRule"
799+
},
800+
"description": {
801+
"type": "string",
802+
"title": "Description",
803+
"description": "Configure the run description that is displayed in output. By default, the description is empty.",
804+
"markdownDescription": "Configure the run description that is displayed in output. By default, the description is empty.\n\n[See help](https://microsoft.github.io/PSRule/v3/concepts/PSRule/en-US/about_PSRule_Options/#executiondescription)",
805+
"default": ""
806+
}
807+
},
808+
"additionalProperties": false
809+
},
787810
"suppression-option": {
788811
"type": "object",
789812
"title": "Suppress rules",
@@ -1123,6 +1146,10 @@
11231146
}
11241147
]
11251148
},
1149+
"run": {
1150+
"type": "object",
1151+
"$ref": "#/definitions/run-option"
1152+
},
11261153
"suppression": {
11271154
"type": "object",
11281155
"oneOf": [

0 commit comments

Comments
 (0)