Merge pull request #302 from Lombiq/issue/OSOE-188

OSOE-188: YAML Linting

.github/actions/check-current-workflow-is-latest/action.yml

@@ -21,7 +21,7 @@ runs:
       shell: pwsh
       run: |
         (Resolve-Path "${{ github.action_path }}/../../../Scripts").Path >> $Env:GITHUB_PATH
-      
+
     - name: Check Current Workflow Equals Latest
       shell: pwsh
       id: check-current-workflow-equals-latest

.github/actions/check-merge-queue-adds/action.yml

@@ -1,7 +1,7 @@
 name: Check Merge Queue Adds
 description: >
-  Checks current pull request timeline add events to determine if it was ever added to a 
-  merge queue. Intentionally not documented in Actions.md since it's only meant for 
+  Checks current pull request timeline add events to determine if it was ever added to a
+  merge queue. Intentionally not documented in Actions.md since it's only meant for
   internal use.
 
 outputs:

.github/actions/get-changed-gha-items/Get-GHA-Items-From-File-List.ps1 → .github/actions/get-changed-gha-items/Get-GhaItemsFromFileList.ps1

@@ -4,6 +4,12 @@ param(
 
 # Filter actions based on files in action directory.
 [array]$actionFiles = $FileIncludeList | Where-Object -FilterScript {
+    $itemDirectory = (Get-Item $PSItem).Directory.FullName
+    $isInGitHubDir = $itemDirectory -like '*/.github/*' -or $itemDirectory -eq '*/.github'
+    if (-not $isInGitHubDir) {
+        return $false
+    }
+
     (Get-Item $PSitem).Directory.GetFiles('action.yml').Count -gt 0 -or
     (Get-Item $PSitem).Directory.GetFiles('action.yaml').Count -gt 0
 }
@@ -13,9 +19,16 @@ param(
 
 # Filter workflow files excluding action yaml file names.
 [array]$workflows = $FileIncludeList | Where-Object -FilterScript {
-    (Get-Item $PSitem).BaseName -ne 'action' -and
-        ((Get-Item $PSitem).Extension -eq '.yml' -or
-         (Get-Item $PSitem).Extension -eq '.yaml')
+    try
+    {
+        (Get-Item $PSitem).BaseName -ne 'action' -and
+            ((Get-Item $PSitem).Extension -eq '.yml' -or
+             (Get-Item $PSitem).Extension -eq '.yaml')
+    }
+    catch
+    {
+        return $false
+    }
 }
 
 # Combine actions and workflows.

.github/actions/get-changed-gha-items/action.yml

@@ -7,7 +7,7 @@ inputs:
     required: false
     default: '@()'
     description: >
-      PowerShell string array of file names to return corresponding GitHub Actions (GHA) items. The 
+      PowerShell string array of file names to return corresponding GitHub Actions (GHA) items. The
       parameter must be a PowerShell string array.
 outputs:
   changed-items:
@@ -20,12 +20,12 @@ runs:
       shell: pwsh
       run: |
         "${{ github.action_path }}" >> $Env:GITHUB_PATH
-        
+
     - name: Get GHA Items
       id: get-gha-items
       shell: pwsh
       run: |
         $params = @{
             FileIncludeList = ${{ inputs.file-include-list }}
         }
-        Get-GHA-Items-From-File-List @params
+        Get-GhaItemsFromFileList @params

.github/actions/spelling/allow.txt

@@ -0,0 +1 @@
+runtimes

.github/actions/yaml-lint/action.yml

@@ -0,0 +1,21 @@
+name: YAML Linting
+description: Runs a linter on YAML files.
+
+
+inputs:
+  config-file-path:
+    description: 'Path to the yamllint configuration file'
+    required: true
+    default: '.yamllint.yaml'
+
+  search-path:
+    description: 'Path to search for YAML files'
+    required: true
+    default: '.'
+
+runs:
+  using: "composite"
+  steps:
+    - name: Run yamllint
+      run: yamllint -c "${{ inputs.config-file-path }}" "${{ inputs.search-path }}"
+      shell: pwsh

.github/workflows/yaml-lint-this-repo.yml

@@ -0,0 +1,16 @@
+name: YAML Linting
+
+# Runs for PRs opened for any branch, and pushes to the dev branch.
+on:
+  pull_request:
+  push:
+    branches:
+      - dev
+
+jobs:
+  yaml-linting:
+    name: YAML Linting
+    uses: Lombiq/GitHub-Actions/.github/workflows/yaml-lint.yml@dev
+    with:
+      config-file-path: '.trunk/configs/.yamllint.yaml'
+      search-path: '.'

.github/workflows/yaml-lint.yml

@@ -0,0 +1,55 @@
+name: YAML Linting
+
+on:
+  workflow_call:
+    secrets:
+      CHECKOUT_TOKEN:
+        required: false
+        description: >
+          The GitHub token to authenticate checkout. Pass in a GitHub personal access token if authenticated submodules
+          are used.
+
+    inputs:
+      timeout-minutes:
+        required: false
+        type: number
+        default: 10
+        description: Configuration for the timeout-minutes parameter of the workflow. GitHub's default is 360.
+      cancel-workflow-on-failure:
+        description: If set to "true", this will cancel the current workflow run with all jobs if this workflow fails.
+        required: false
+        type: string
+        default: "true"
+      config-file-path:
+        description: 'Path to the yamllint configuration file'
+        required: true
+        type: string
+        default: '.yamllint.yaml'
+      search-path:
+        description: 'Path to search for YAML files'
+        required: true
+        type: string
+        default: '.'
+
+jobs:
+  yaml-linting:
+    runs-on: ubuntu-22.04
+    name: YAML Linting Job
+    timeout-minutes: ${{ inputs.timeout-minutes }}
+    steps:
+      - name: Checkout
+        uses: Lombiq/GitHub-Actions/.github/actions/checkout@dev
+        with:
+          token: ${{ secrets.CHECKOUT_TOKEN }}
+
+      - name: YAML Linting
+        uses: Lombiq/GitHub-Actions/.github/actions/yaml-lint@dev
+        with:
+          config-file-path: ${{ inputs.config-file-path }}
+          search-path: ${{ inputs.search-path }}
+
+      - name: Cancel Workflow on Failure
+        if: failure() && inputs.cancel-workflow-on-failure == 'true'
+        uses: Lombiq/GitHub-Actions/.github/actions/cancel-workflow@dev
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.trunk/.gitignore

@@ -0,0 +1,8 @@
+*out
+*logs
+*actions
+*notifications
+*tools
+plugins
+user_trunk.yaml
+user.yaml

.trunk/configs/.yamllint.yaml

@@ -0,0 +1,16 @@
+yaml-files:
+  - '*.yaml'
+  - '*.yml'
+  - '.yamllint'
+
+ignore: |
+  **/node_modules/**
+  **/.trunk/**
+
+rules:
+    trailing-spaces: {}
+    key-duplicates: {}
+    quoted-strings: {
+        quote-type: any,
+        required: false
+    }

.trunk/trunk.yaml

@@ -0,0 +1,20 @@
+# This file controls the behavior of Trunk: https://docs.trunk.io/cli
+# To learn more about the format of this file, see https://docs.trunk.io/reference/trunk-yaml
+version: 0.1
+cli:
+    version: 1.17.2
+# Trunk provides extensibility via plugins. (https://docs.trunk.io/plugins)
+plugins:
+    sources:
+        - id: trunk
+          ref: v1.3.0
+          uri: https://github.com/trunk-io/plugins
+# Many linters and tools depend on runtimes - configure them here. (https://docs.trunk.io/runtimes)
+runtimes:
+    enabled:
+        - [email protected]
+        - [email protected]
+# This is the section where you manage your linters. (https://docs.trunk.io/check/configuration)
+lint:
+    enabled:
+        - [email protected]

Docs/Workflows.md

@@ -30,6 +30,7 @@ These features are designed to reduce resource usage (like paid GitHub Actions m
 - [Spell-checking](Workflows/Productivity/SpellChecking.md)
 - [Validate pull request](Workflows/Productivity/ValidatePullRequest.md)
 - [Validate submodule](Workflows/Productivity/ValidateSubmodule.md)
+- [Lint YAML files](Workflows/Productivity/YamlLinting.md)
 
 ## Azure hosting
 

Docs/Workflows/Productivity/YamlLinting.md

@@ -0,0 +1,34 @@
+# YAML Linting
+
+This solution uses [`yamllint`](https://github.com/adrienverge/yamllint) for linting YAML files according to a configuration file. Such a configuration file includes a set of rules that are checked against when linting the files and can be found in `/.trunk/configs/.yamllint.yaml`.
+
+You would typically consume the corresponding GHA workflow for YAML linting like this:
+
+```yaml
+...
+
+jobs:
+    yaml-linting:
+        name: YAML Linting
+        uses: Lombiq/GitHub-Actions/.github/workflows/yaml-lint.yml@dev
+        with:
+            config-file-path: 'tools/Lombiq.GitHub.Actions/.trunk/configs/.yamllint.yaml'
+            search-path: '.'
+```
+
+Where:
+
+- `config-file-path`: Specifies the location of the `yamllint` rules file to use. See more details about such file [here](https://yamllint.readthedocs.io/en/stable/rules.html).
+- `search-path`: Where the files to lint should be searched.
+
+## Integration with VSCode
+
+During local development, YAML linting can be enabled in VSCode via the [Trunk Check](https://marketplace.visualstudio.com/items?itemName=Trunk.io) extension. Such a tool will look for the `yamllint` configuration file located in the folder `/.trunk`, which is already setup.
+
+Additionally, the linter can be run as a standalone tool:
+
+```bash
+yamllint -c ./.trunk/configs/.yamllint.yaml ./github
+```
+
+Optionally, the Trunk Code extension can be used in conjunction with the [YAML by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension, which provides IntelliSense and description-on-hover capabilities based on a schema.