Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/lint-caller.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ jobs:
mise-version: "2026.10.19"
# renovate: datasource=github-releases depName=golangci/golangci-lint
# golangci-lint-version: "v2.12.2"
# renovate: datasource=nuget depName=PSScriptAnalyzer registryUrl=https://www.powershellgallery.com/api/v2/
psscriptanalyzer-version: "1.25.0"
lint-config-dir: config-sync/files
# config-sync/templates holds a root biome.json for other repositories,
# which Biome rejects as a second root config in this one.
Expand All @@ -48,6 +50,8 @@ jobs:
with:
# renovate: datasource=github-releases depName=jdx/mise
mise-version: "2026.10.19"
# renovate: datasource=nuget depName=PSScriptAnalyzer registryUrl=https://www.powershellgallery.com/api/v2/
psscriptanalyzer-version: "1.25.0"
lint-config-dir: config-sync/files
lint-biome-exclude: config-sync/templates/* # See the job above.
lint-job-mode: single
Expand Down
18 changes: 16 additions & 2 deletions .github/workflows/lint-include.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@ on:
required: false
type: string
default: "go.mod"
psscriptanalyzer-version:
description: "PSScriptAnalyzer version to install from the PowerShell Gallery. Without it, PSScriptAnalyzer skips
the repository's PowerShell files with a warning"
required: false
type: string
default: ""
lint-config-dir:
description: "Directory containing optional linter config files"
required: false
Expand Down Expand Up @@ -124,6 +130,12 @@ on:
required: false
type: boolean
default: false
lint-psscriptanalyzer:
description: "Run PSScriptAnalyzer (PowerShell linting) when the repository has *.ps1, *.psm1 or *.psd1 files — uploads
SARIF"
required: false
type: boolean
default: false
lint-config-drift:
description: "Check local config files match central DevSecNinja/.github repo"
required: false
Expand All @@ -140,8 +152,8 @@ on:
type: boolean
default: false
upload-sarif:
description: "Upload checkov/trivy/zizmor/ruff/biome results to GitHub code scanning (requires GitHub Advanced Security).
Set false for private repos without GHAS to gate on exit codes with console output instead."
description: "Upload checkov/trivy/zizmor/ruff/biome/psscriptanalyzer results to GitHub code scanning (requires GitHub
Advanced Security). Set false for private repos without GHAS to gate on exit codes with console output instead."
required: false
type: boolean
default: true
Expand Down Expand Up @@ -173,6 +185,7 @@ jobs:
mise-version: ${{ inputs.mise-version }}
golangci-lint-version: ${{ inputs.golangci-lint-version }}
go-version-file: ${{ inputs.go-version-file }}
psscriptanalyzer-version: ${{ inputs.psscriptanalyzer-version }}
lint-config-dir: ${{ inputs.lint-config-dir }}
lint-fail-on-error: ${{ inputs.lint-fail-on-error }}
lint-dprint: ${{ inputs.lint-dprint }}
Expand All @@ -192,6 +205,7 @@ jobs:
lint-biome: ${{ inputs.lint-biome }}
lint-biome-exclude: ${{ inputs.lint-biome-exclude }}
lint-biome-with-eslint: ${{ inputs.lint-biome-with-eslint }}
lint-psscriptanalyzer: ${{ inputs.lint-psscriptanalyzer }}
lint-config-drift: ${{ inputs.lint-config-drift }}
lint-inline-scripts: ${{ inputs.lint-inline-scripts }}
lint-inline-scripts-blocking: ${{ inputs.lint-inline-scripts-blocking }}
Expand Down
95 changes: 93 additions & 2 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ on:
required: false
type: string
default: "go.mod"
psscriptanalyzer-version:
description: "PSScriptAnalyzer version to install from the PowerShell Gallery. Without it, PSScriptAnalyzer skips
the repository's PowerShell files with a warning"
required: false
type: string
default: ""
lint-config-dir:
description: "Directory containing optional linter config files"
required: false
Expand Down Expand Up @@ -116,6 +122,12 @@ on:
required: false
type: boolean
default: false
lint-psscriptanalyzer:
description: "Run PSScriptAnalyzer (PowerShell linting) when the repository has *.ps1, *.psm1 or *.psd1 files — uploads
SARIF"
required: false
type: boolean
default: true
lint-config-drift:
description: "Check local config files match central DevSecNinja/.github repo"
required: false
Expand All @@ -135,8 +147,8 @@ on:
type: boolean
default: false
upload-sarif:
description: "Upload checkov/trivy/zizmor/ruff/biome results to GitHub code scanning (requires GitHub Advanced Security).
Set false for private repos without GHAS to gate on exit codes with console output instead."
description: "Upload checkov/trivy/zizmor/ruff/biome/psscriptanalyzer results to GitHub code scanning (requires GitHub
Advanced Security). Set false for private repos without GHAS to gate on exit codes with console output instead."
required: false
type: boolean
default: true
Expand Down Expand Up @@ -822,6 +834,61 @@ jobs:
sarif_file: ${{ runner.temp }}/biome.sarif
category: biome

psscriptanalyzer:
name: psscriptanalyzer
if: ${{ inputs.lint-psscriptanalyzer && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private))
}}
continue-on-error: ${{ ! inputs.lint-fail-on-error }}
runs-on: ubuntu-24.04
timeout-minutes: 10
permissions:
contents: read
security-events: write
steps:
- name: Checkout lint scripts
# The linter scripts ship with this reusable workflow: fetch them from
# the same commit of DevSecNinja/.github that the caller pinned.
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ job.workflow_repository }}
ref: ${{ job.workflow_sha }}
path: .devsecninja-lint
sparse-checkout: |-
scripts/lint/
scripts/lint-inline-scripts.py
sparse-checkout-cone-mode: false
persist-credentials: false

- name: Move lint scripts out of the workspace
# Outside the workspace the caller's linters don't scan them, and the
# code checkout doesn't delete them.
run: mv .devsecninja-lint "${RUNNER_TEMP}/devsecninja-lint"

- name: Checkout code
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Find PowerShell files
# Repositories without them skip PSScriptAnalyzer.
id: powershell-files
run: bash "${RUNNER_TEMP}/devsecninja-lint/scripts/lint/detect-language.sh" powershell

- name: Run PSScriptAnalyzer
id: psscriptanalyzer
if: ${{ steps.powershell-files.outputs.found == 'true' }}
env:
PSSCRIPTANALYZER_VERSION: ${{ inputs.psscriptanalyzer-version }}
UPLOAD_SARIF: ${{ inputs.upload-sarif }}
run: bash "${RUNNER_TEMP}/devsecninja-lint/scripts/lint/psscriptanalyzer.sh"

- name: Upload SARIF report
if: ${{ !cancelled() && steps.psscriptanalyzer.outputs.sarif == 'true' }}
uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
with:
sarif_file: ${{ runner.temp }}/psscriptanalyzer.sarif
category: psscriptanalyzer

config-drift:
name: config drift
if: ${{ inputs.lint-config-drift && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private))
Expand Down Expand Up @@ -960,6 +1027,12 @@ jobs:
STEP_ASIDE_FOR: ${{ !inputs.lint-biome-with-eslint && 'eslint' || '' }}
run: bash "${RUNNER_TEMP}/devsecninja-lint/scripts/lint/detect-language.sh" web

- name: Find PowerShell files
# Repositories without them skip PSScriptAnalyzer.
id: powershell-files
if: ${{ inputs.lint-psscriptanalyzer }}
run: bash "${RUNNER_TEMP}/devsecninja-lint/scripts/lint/detect-language.sh" powershell

- name: Install mise
if: >-
${{ inputs.lint-dprint || inputs.lint-yamlfmt || inputs.lint-yamllint || inputs.lint-actionlint || inputs.lint-gitleaks
Expand Down Expand Up @@ -1183,6 +1256,24 @@ jobs:
sarif_file: ${{ runner.temp }}/biome.sarif
category: biome

- name: Run PSScriptAnalyzer
id: psscriptanalyzer
if: ${{ steps.powershell-files.outputs.found == 'true' }}
continue-on-error: true
env:
PSSCRIPTANALYZER_VERSION: ${{ inputs.psscriptanalyzer-version }}
UPLOAD_SARIF: ${{ inputs.upload-sarif }}
run: bash "${RUNNER_TEMP}/devsecninja-lint/scripts/lint/psscriptanalyzer.sh"

- name: Upload PSScriptAnalyzer SARIF report
id: psscriptanalyzer-sarif
if: ${{ !cancelled() && steps.psscriptanalyzer.outputs.sarif == 'true' }}
continue-on-error: true
uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
with:
sarif_file: ${{ runner.temp }}/psscriptanalyzer.sarif
category: psscriptanalyzer

- name: Check config drift against central repo
id: config-drift
if: ${{ inputs.lint-config-drift }}
Expand Down
6 changes: 5 additions & 1 deletion .renovate/customManagers.json5
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,16 @@
"/workflow-templates/.+\\.ya?ml$/",
],
matchStrings: [
"# renovate: datasource=(?<datasource>\\S+)(?: depName=(?<depName>\\S+))?\\n\\s+[\\w-]*version: \\[?\"?(?<currentValue>[^\\s\"\\[\\],]+)\"?\\]?[ \\t]*(?:#[^\\n]*)?(?:\\r?\\n|$)",
"# renovate: datasource=(?<datasource>\\S+)(?: depName=(?<depName>\\S+))?(?: registryUrl=(?<registryUrl>\\S+))?\\n\\s+[\\w-]*version: \\[?\"?(?<currentValue>[^\\s\"\\[\\],]+)\"?\\]?[ \\t]*(?:#[^\\n]*)?(?:\\r?\\n|$)",
],
datasourceTemplate: "{{{datasource}}}",
// `depName=` may be omitted for the runtime datasources, e.g.
// # renovate: datasource=python-version
// python-version: [3.14]
// and `registryUrl=` names a registry other than the datasource's
// default, e.g. the PowerShell Gallery for a module:
// # renovate: datasource=nuget depName=PSScriptAnalyzer registryUrl=https://www.powershellgallery.com/api/v2/
// psscriptanalyzer-version: "1.25.0"
// A single-element matrix list is tracked like a scalar; a list with
// more entries is not tracked at all (the match must end the line;
// Renovate's RE2 engine has no lookahead, so the line end is consumed). Without
Expand Down
56 changes: 56 additions & 0 deletions config-sync/templates/PSScriptAnalyzerSettings.psd1
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
@{
# Template - adapt per repo. Settings for PSScriptAnalyzer, which the shared
# Lint workflow (lint-psscriptanalyzer) runs on the repository's *.ps1, *.psm1
# and *.psd1 files. Errors and warnings fail the check; information findings
# are annotated only. Based on DevSecNinja/windows-iso-maker's settings.

# Start from the full built-in rule set, then tighten a few rules.
IncludeDefaultRules = $true

# ParseError must stay listed: without it, a script that doesn't parse passes.
Severity = @('ParseError', 'Error', 'Warning', 'Information')

ExcludeRules = @(
# Files are UTF-8 without a BOM (.editorconfig), the same on Linux and
# Windows; non-ASCII characters in comments would trip this rule.
'PSUseBOMForUnicodeEncodedFile',

# PSScriptAnalyzer bug (as of 1.25.0): when a command has no parameter
# set, this rule throws a NullReferenceException that aborts the whole
# run, not just the finding. Re-enable it once
# https://github.com/PowerShell/PSScriptAnalyzer/issues/1708 is fixed.
'PSUseCorrectCasing'
)

Rules = @{
PSUseApprovedVerbs = @{
Enable = $true
}

# Comment-based help on every exported function.
PSProvideCommentHelp = @{
Enable = $true
ExportedOnly = $true
BlockComment = $true
VSCodeSnippetCorrection = $false
Placement = 'begin'
}

# No aliases: full command names only.
PSAvoidUsingCmdletAliases = @{
Enable = $true
AllowList = @()
}

# Honour -WhatIf in functions that change state.
PSUseShouldProcessForStateChangingFunctions = @{
Enable = $true
}

# Syntax that runs on both Windows PowerShell 5.1 and PowerShell 7.
PSUseCompatibleSyntax = @{
Enable = $true
TargetVersions = @('5.1', '7.0')
}
}
}
13 changes: 13 additions & 0 deletions config-sync/templates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,3 +118,16 @@ usual template header. Config-sync doesn't add it to a repo that has
`biome.jsonc`. The `customManagers:biomeVersions` Renovate preset, part of the
shared Renovate config, keeps its `$schema` version in step with the pinned
Biome.

## PSScriptAnalyzerSettings.psd1

Settings for PSScriptAnalyzer, which the shared Lint workflow runs when the
repo has `*.ps1`, `*.psm1` or `*.psd1` files (`lint-psscriptanalyzer`, with the
`psscriptanalyzer-version` input). It starts from DevSecNinja/windows-iso-maker's
settings: every default rule plus approved verbs, comment-based help on
exported functions, no aliases, `ShouldProcess` for state changes and syntax
that runs on Windows PowerShell 5.1 and PowerShell 7. It skips the BOM rule
(files are UTF-8 without a BOM) and `PSUseCorrectCasing`, which crashes whole
runs until
[PowerShell/PSScriptAnalyzer#1708](https://github.com/PowerShell/PSScriptAnalyzer/issues/1708)
is fixed.
19 changes: 17 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ workflow, so it calls `scripts/apm-materialize/` from its own checkout.

### Lint (`lint.yml`)

Runs up to fifteen linters. By default, linter failures are reported without
Runs up to sixteen linters. By default, linter failures are reported without
failing the workflow; set `lint-fail-on-error` to `true` to make lint failures
fail the workflow. Toggle individual linters on/off with boolean inputs; all
linter toggles default to `true`.
Expand Down Expand Up @@ -201,6 +201,19 @@ APM-deployed agent files, `node_modules`, `.venv*`).
Biome steps aside in repositories that configure ESLint (`eslint.config.*`,
`.eslintrc*`), which lint in their own CI with their plugins; set
`lint-biome-with-eslint` to run both. dprint formats only Markdown.
- **PSScriptAnalyzer** (`lint-psscriptanalyzer`, PowerShell, after v4.5.0)
analyzes the `*.ps1`, `*.psm1` and `*.psd1` files with the runner's `pwsh`.
It needs no mise: pass `psscriptanalyzer-version` instead, with a Renovate
annotation (see the [workflow template](../workflow-templates/lint.yml)).
Without it, a repository with PowerShell files gets a warning that names the
fix, and the linter skips instead of failing. Once the version is set,
findings fail as below. That version is installed from the PowerShell
Gallery unless the runner has it already. The repository's
`PSScriptAnalyzerSettings.psd1` configures it; config-sync's
[template](../config-sync/templates/PSScriptAnalyzerSettings.psd1) is a
starting point. Errors and warnings fail the linter, information findings
are only annotated. Findings are annotated on the PR, and with `upload-sarif`
they also go to code scanning (category `psscriptanalyzer`).

**Inline scripts.** Code in a `run:` block is out of reach of linters,
formatters and tests, so a `run:` step may hold exactly one line with one
Expand Down Expand Up @@ -240,10 +253,11 @@ runner's system Python, which ships PyYAML (`ubuntu-24.04`).
| `mise-version` | **Required.** mise version to install. |
| `golangci-lint-version` | **Required.** golangci-lint version to install. |
| `go-version-file` | Go version file for setup-go. Default: `go.mod`. |
| `psscriptanalyzer-version` | PSScriptAnalyzer version; skips with a warning if unset. After v4.5.0. |
| `lint-config-dir` | Optional linter config directory. Default: `""`. |
| `lint-fail-on-error` | Fail when a linter fails. Default: `false`. |
| `lint-job-mode` | `auto`, `single`, or `parallel` (see above). Default: `auto`. v3.3.0+. |
| `upload-sarif` | Upload SARIF (checkov, trivy, zizmor, ruff, biome). Default: `true`. |
| `upload-sarif` | Upload SARIF (checkov, trivy, zizmor, language linters). Default: on. |
| `lint-dprint` | Markdown formatting (dprint). Default: `true`. |
| `lint-yamlfmt` | YAML formatting (yamlfmt). Default: `true`. |
| `lint-yamllint` | YAML linting (yamllint). Default: `true`. |
Expand All @@ -259,6 +273,7 @@ runner's system Python, which ships PyYAML (`ubuntu-24.04`).
| `lint-biome` | JS/TS/JSON/CSS linting (Biome). Default: `true`. After v4.5.0. |
| `lint-biome-exclude` | Bash pattern of paths Biome skips. Default: `""`. After v4.5.0. |
| `lint-biome-with-eslint` | Run Biome next to ESLint. Default: `false`. After v4.5.0. |
| `lint-psscriptanalyzer` | PowerShell linting (PSScriptAnalyzer). Default: `true`. After v4.5.0. |
| `lint-config-drift` | Config-drift check. Default: `false`. |
| `lint-inline-scripts` | Inline-script check (see above). Default: `true`. After v4.4.0. |
| `lint-inline-scripts-blocking` | Report inline scripts as errors. Default: `false`. After v4.4.0. |
Expand Down
17 changes: 16 additions & 1 deletion docs/design-decisions/0001-reusable-workflow-version-inputs.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,20 @@ It does **not** apply to:
- Non-version configuration inputs (file paths, feature toggles, labels, …).
These may and should have sensible defaults to keep callers terse.

**Conditional version inputs.** A version input for a tool that runs only when
the calling repository has matching files (Go code, PowerShell scripts, …) MAY
be declared `required: false`, so repositories without those files need no
version. It MUST still have no version default (`default: ""`): the workflow
never picks a version for the caller. When the tool would run and the caller
passed no version, the workflow MUST either fail with guidance, or skip the
tool with a `::warning` that names the input to set. The caller then owns the
version exactly as with `required: true`. In `lint.yml`,
`golangci-lint-version` (with `go.mod`) fails, and `psscriptanalyzer-version`
(with `*.ps1`, `*.psm1` or `*.psd1` files) skips with a warning, the rule
chosen for the language linters (#539): adopting a linter must not
turn a caller's lint red before it has picked a version. Once the version is
set, findings fail as usual.

## Consequences

### Pros
Expand Down Expand Up @@ -129,7 +143,8 @@ It does **not** apply to:

## Compliance

- `lint.yml` — `mise-version` and `golangci-lint-version` required ✅
- `lint.yml` — `mise-version` required ✅; `golangci-lint-version` and
`psscriptanalyzer-version` conditional, no default (see the Decision) ✅
- `release.yml` — `mise-version` required ✅
- `autofix.yml` — `mise-version` required ✅
- `config-sync.yml`, `label-sync.yml`, `labeler.yml`, `todo-to-issue.yml` —
Expand Down
1 change: 1 addition & 0 deletions scripts/lint/language-files.sh
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ web)
;;
# ESLint configs: Biome steps aside for repositories that lint with ESLint.
eslint) patterns=('**/eslint.config.*' '**/.eslintrc' '**/.eslintrc.*') ;;
powershell) patterns=('**/*.ps1' '**/*.psm1' '**/*.psd1') ;;
*)
echo "::error::language-files.sh: unknown language '$1'" >&2
exit 2
Expand Down
Loading
Loading