feat(build): add TFLint reusable GitHub Actions workflow (#229)

# Pull Request

## Description

<!-- Brief description of changes. Link related issues using Closes #123
-->

Closes #201

Added **TFLint** as a reusable CI workflow for Terraform linting, with a
PowerShell wrapper, Pester tests, and full integration into the PR
validation and main pipelines. TFLint **v0.61.0** is pinned in both the
devcontainer and the GitHub Actions workflow.

A new reusable *terraform-lint.yml* workflow runs TFLint recursively
against the *deploy/001-iac* directory using the shared *.tflint.hcl*
config. The PowerShell wrapper *Invoke-TFLint.ps1* parses JSON output,
emits CI annotations, and writes results to *logs/tflint-results.json*.
The workflow supports a **soft-fail** input for gradual adoption.

The `terraform-lint` job was wired into both
*.github/workflows/pr-validation.yml* and *.github/workflows/main.yml*,
with the main workflow gating releases on lint passing via the
`release-please` job's `needs` array. All GitHub Actions references use
SHA-pinned versions for supply chain security.

Pester unit tests cover tool availability detection, clean runs,
violation reporting, and output file creation, using existing mock
infrastructure and new Terraform test fixtures.

## Type of Change
<!-- Mark relevant options with [x] -->

- [ ] 🐛 Bug fix (non-breaking change fixing an issue)
- [x] ✨ New feature (non-breaking change adding functionality)
- [ ] 💥 Breaking change (fix or feature causing existing functionality
to change)
- [ ] 📚 Documentation update
- [x] 🏗️ Infrastructure change (Terraform/IaC)
- [ ] ♻️ Refactoring (no functional changes)

## Component(s) Affected
<!-- Mark all that apply -->

- [ ] `deploy/000-prerequisites` - Azure subscription setup
- [ ] `deploy/001-iac` - Terraform infrastructure
- [ ] `deploy/002-setup` - OSMO control plane / Helm
- [ ] `deploy/004-workflow` - Training workflows
- [ ] `src/training` - Python training scripts
- [ ] `docs/` - Documentation

## Testing Performed
<!-- Describe testing. Check applicable items -->

- [ ] Terraform `plan` reviewed (no unexpected changes)
- [ ] Terraform `apply` tested in dev environment
- [ ] Training scripts tested locally with Isaac Sim
- [ ] OSMO workflow submitted successfully
- [ ] Smoke tests passed (`smoke_test_azure.py`)

## Documentation Impact
<!-- Select one -->

- [x] No documentation changes needed
- [ ] Documentation updated in this PR
- [ ] Documentation issue filed

## Bug Fix Checklist

*Complete this section for bug fix PRs. Skip for other contribution
types.*

- [ ] Linked to issue being fixed
- [ ] Regression test included, OR
- [ ] Justification for no regression test:

## Checklist

- [x] My code follows the [project conventions](copilot-instructions.md)
- [x] Commit messages follow [conventional commit
format](instructions/commit-message.instructions.md)
- [x] I have performed a self-review
- [x] Documentation impact assessed above
- [ ] No new linting warnings introduced

Author: WilliamBerryiii

.devcontainer/devcontainer.json

@@ -92,7 +92,7 @@
 		"setup-dev": "./setup-dev.sh --disable-venv",
 		"npm-install": "npm install",
 		"apt": "sudo apt update && sudo apt install -y shellcheck jq unzip",
-		"tflint": "curl -s https://raw.githubusercontent.com/terraform-linters/tflint/master/install_linux.sh | bash",
+		"tflint": "TFLINT_VERSION=v0.61.0 && curl -sSfL \"https://raw.githubusercontent.com/terraform-linters/tflint/${TFLINT_VERSION}/install_linux.sh\" | bash && tflint --init",
 		"actionlint": "ACTIONLINT_VERSION=1.7.10 && ACTIONLINT_SHA256=f4c76b71db5755a713e6055cbb0857ed07e103e028bda117817660ebadb4386f && curl -sSfL \"https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz\" -o /tmp/actionlint.tar.gz && echo \"${ACTIONLINT_SHA256} /tmp/actionlint.tar.gz\" | sha256sum -c --quiet - && sudo tar -xzf /tmp/actionlint.tar.gz -C /usr/local/bin actionlint && rm /tmp/actionlint.tar.gz",
 		"update-bashrc": "echo 'export PATH=\"${containerWorkspaceFolder}/scripts:${containerWorkspaceFolder}/node_modules/.bin:$PATH\"' | sudo tee -a  ~/.bashrc",
 		"osmo-cli": "curl -fsSL https://raw.githubusercontent.com/NVIDIA/OSMO/refs/heads/main/install.sh | bash || true",

.github/copilot-instructions.md

@@ -187,7 +187,7 @@ Run `npm install` (or `npm ci`) before any `npm run` lint commands. `shellcheck`
 
 ### Linting
 
-* `npm run lint:all` runs `lint:md` + `lint:ps` + `lint:links` + `lint:yaml` in sequence
+* `npm run lint:all` runs `lint:md` + `lint:ps` + `lint:links` + `lint:yaml` + `lint:tf` in sequence
 * `npm run spell-check` and `npm run format:tables` are NOT included in `lint:all` — run them separately
 * `npm run lint:md:fix` and `npm run format:tables` auto-fix markdown issues
 * `.copilot-tracking/` is excluded from markdown linting via `.markdownlint-cli2.jsonc`

.github/workflows/main.yml

@@ -113,6 +113,15 @@ jobs:
     permissions:
       contents: read
 
+  # Terraform linting using TFLint
+  terraform-lint:
+    name: Terraform Lint
+    uses: ./.github/workflows/terraform-lint.yml
+    with:
+      soft-fail: true
+    permissions:
+      contents: read
+
   # CodeQL security analysis
   codeql-analysis:
     name: CodeQL Analysis
@@ -137,6 +146,7 @@ jobs:
       - pester-tests
       - pytest-tests
       - python-lint
+      - terraform-lint
       - codeql-analysis
     name: Release Please
     runs-on: ubuntu-latest

.github/workflows/pr-validation.yml

@@ -138,6 +138,15 @@ jobs:
     permissions:
       contents: read
 
+  # Terraform linting using TFLint
+  terraform-lint:
+    name: Terraform Lint
+    uses: ./.github/workflows/terraform-lint.yml
+    with:
+      soft-fail: true
+    permissions:
+      contents: read
+
   # CodeQL security analysis
   codeql-analysis:
     name: CodeQL Analysis

.github/workflows/terraform-lint.yml

@@ -0,0 +1,55 @@
+name: Terraform Lint
+
+on:
+  workflow_call:
+    inputs:
+      soft-fail:
+        description: 'Whether to continue on TFLint violations'
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: pwsh
+
+jobs:
+  tflint:
+    name: TFLint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Create logs directory
+        run: New-Item -ItemType Directory -Force -Path logs | Out-Null
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@4cb9feea73331a35b422df102992a03a44a3bb33 # v6.2.1
+        with:
+          tflint_version: v0.61.0
+          cache: true
+
+      - name: Init TFLint
+        run: tflint --init --config (Resolve-Path .tflint.hcl) --recursive
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Run TFLint
+        continue-on-error: ${{ inputs.soft-fail }}
+        run: shared/ci/linting/Invoke-TFLint.ps1
+
+      - name: Upload TFLint results
+        if: always()
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: tflint-results
+          path: logs/tflint-results.json
+          retention-days: 30

package.json

@@ -14,7 +14,8 @@
     "lint:ps": "pwsh -File shared/ci/linting/Invoke-PSScriptAnalyzer.ps1",
     "lint:links": "pwsh -File shared/ci/linting/Invoke-LinkLanguageCheck.ps1",
     "lint:yaml": "pwsh -File shared/ci/linting/Invoke-YamlLint.ps1",
-    "lint:all": "npm run lint:md && npm run lint:ps && npm run lint:links && npm run lint:yaml",
+    "lint:tf": "pwsh -File shared/ci/linting/Invoke-TFLint.ps1",
+    "lint:all": "npm run lint:md && npm run lint:ps && npm run lint:links && npm run lint:yaml && npm run lint:tf",
     "format:tables": "markdown-table-formatter \"**/*.md\"",
     "test:ps": "pwsh -File ./shared/ci/tests/Invoke-PesterTests.ps1",
     "prepare": "husky",

shared/ci/linting/Invoke-TFLint.ps1

@@ -0,0 +1,105 @@
+#!/usr/bin/env pwsh
+# Copyright (c) Microsoft Corporation.
+# SPDX-License-Identifier: MIT
+
+#Requires -Version 7.0
+
+<#
+.SYNOPSIS
+    Runs TFLint across Terraform directories.
+.DESCRIPTION
+    Wraps tflint --recursive with shared .tflint.hcl config. Reports violations
+    via CI annotations and writes JSON results to logs/.
+.PARAMETER ConfigPath
+    Path to .tflint.hcl. Defaults to repo root .tflint.hcl.
+.PARAMETER OutputPath
+    Path for JSON results. Defaults to logs/tflint-results.json.
+.PARAMETER TerraformDir
+    Directory containing Terraform files. Defaults to infrastructure/terraform.
+#>
+
+[CmdletBinding()]
+param(
+    [string]$ConfigPath,
+    [string]$OutputPath,
+    [string]$TerraformDir
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+Import-Module (Join-Path $PSScriptRoot "Modules/LintingHelpers.psm1") -Force
+Import-Module (Join-Path $PSScriptRoot "../../../scripts/lib/Modules/CIHelpers.psm1") -Force
+
+function Invoke-TFLintCore {
+    [CmdletBinding()]
+    param(
+        [string]$ConfigPath,
+        [string]$OutputPath,
+        [string]$TerraformDir
+    )
+
+    $repoRoot = & git rev-parse --show-toplevel 2>$null
+    if (-not $repoRoot) {
+        $repoRoot = (Get-Item $PSScriptRoot).Parent.Parent.Parent.FullName
+    }
+
+    if (-not $ConfigPath) { $ConfigPath = Join-Path $repoRoot '.tflint.hcl' }
+    if (-not $OutputPath) { $OutputPath = Join-Path $repoRoot 'logs/tflint-results.json' }
+    if (-not $TerraformDir) { $TerraformDir = Join-Path $repoRoot 'infrastructure/terraform' }
+
+    $outputDir = Split-Path $OutputPath -Parent
+    if (-not (Test-Path $outputDir)) {
+        New-Item -ItemType Directory -Force -Path $outputDir | Out-Null
+    }
+
+    if (-not (Get-Command tflint -ErrorAction SilentlyContinue)) {
+        Write-CIAnnotation -Level Error -Message 'tflint is not installed or not in PATH'
+        return 1
+    }
+
+    $resolvedConfig = Resolve-Path $ConfigPath
+
+    # Run TFLint with JSON output for parsing
+    $jsonOutput = & tflint --recursive --chdir="$TerraformDir" --config $resolvedConfig --format json 2>&1
+    $exitCode = $LASTEXITCODE
+
+    $jsonOutput | Out-File -FilePath $OutputPath -Encoding utf8
+
+    # Parse results for CI annotations
+    $results = $null
+    try {
+        $results = $jsonOutput | ConvertFrom-Json -ErrorAction Stop
+        if ($results.issues) {
+            foreach ($issue in $results.issues) {
+                $level = if ($issue.rule.severity -eq 'error') { 'Error' } else { 'Warning' }
+                Write-CIAnnotation -Level $level -Message $issue.message `
+                    -File $issue.range.filename -Line $issue.range.start.line
+            }
+        }
+    }
+    catch {
+        Write-Warning "Failed to parse tflint JSON output: $($_.Exception.Message)"
+    }
+
+    $issueCount = if ($results.issues) { $results.issues.Count } else { 0 }
+    $summary = "TFLint: $issueCount issue(s) found in $TerraformDir"
+    Write-CIStepSummary -Content $summary
+    Write-Host $summary
+
+    return $exitCode
+}
+
+#region Main Execution
+if ($MyInvocation.InvocationName -ne '.') {
+    try {
+        $exitCode = Invoke-TFLintCore @PSBoundParameters
+        exit $exitCode
+    }
+    catch {
+        Write-Error -ErrorAction Continue "Invoke-TFLint failed: $($_.Exception.Message)"
+        Write-CIAnnotation -Level Error -Message $_.Exception.Message
+        exit 1
+    }
+}
+#endregion Main Execution

shared/ci/tests/Fixtures/Terraform/invalid/main.tf

@@ -0,0 +1,2 @@
+variable "MyVariable" {
+}

shared/ci/tests/Fixtures/Terraform/valid/main.tf

@@ -0,0 +1,3 @@
+terraform {
+  required_version = ">= 1.0"
+}

shared/ci/tests/linting/Invoke-TFLint.Tests.ps1

@@ -0,0 +1,71 @@
+# Copyright (c) Microsoft Corporation.
+# SPDX-License-Identifier: MIT
+
+#Requires -Version 7.0
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0' }
+
+BeforeAll {
+    . $PSScriptRoot/../../linting/Invoke-TFLint.ps1
+    $ErrorActionPreference = 'Continue'
+    Import-Module (Join-Path $PSScriptRoot '../Mocks/GitMocks.psm1') -Force
+    function tflint { }
+}
+
+Describe 'Invoke-TFLintCore' -Tag 'Unit' {
+    BeforeAll { Save-CIEnvironment }
+    AfterAll  { Restore-CIEnvironment }
+
+    BeforeEach {
+        $script:MockFiles = Initialize-MockCIEnvironment -Workspace $TestDrive
+        $script:TestOutputPath = Join-Path $TestDrive 'logs/tflint-results.json'
+        $script:TestTerraformDir = Join-Path $TestDrive 'infrastructure/terraform'
+        $script:TestConfigPath = Join-Path $TestDrive '.tflint.hcl'
+
+        New-Item -ItemType Directory -Force -Path $script:TestTerraformDir | Out-Null
+        '{}' | Out-File $script:TestConfigPath
+
+        Mock git { return $TestDrive } -ParameterFilter { $args[0] -eq 'rev-parse' }
+        Mock tflint { return '{"issues":[],"errors":[]}' }
+    }
+
+    AfterEach {
+        Restore-CIEnvironment
+        Remove-MockCIFiles -MockFiles $script:MockFiles
+    }
+
+    Context 'tool availability' {
+        It 'Returns 1 when tflint is not installed' {
+            Mock Get-Command { return $null } -ParameterFilter { $Name -eq 'tflint' }
+            $result = Invoke-TFLintCore -ConfigPath $script:TestConfigPath `
+                -OutputPath $script:TestOutputPath -TerraformDir $script:TestTerraformDir
+            $result | Should -Be 1
+        }
+    }
+
+    Context 'clean run' {
+        It 'Returns 0 when no issues found' {
+            Mock tflint { $global:LASTEXITCODE = 0; return '{"issues":[],"errors":[]}' }
+            $result = Invoke-TFLintCore -ConfigPath $script:TestConfigPath `
+                -OutputPath $script:TestOutputPath -TerraformDir $script:TestTerraformDir
+            $result | Should -Be 0
+        }
+    }
+
+    Context 'violations found' {
+        It 'Returns non-zero when violations found' {
+            Mock tflint { $global:LASTEXITCODE = 2; return '{"issues":[{"rule":{"name":"terraform_naming_convention","severity":"warning","link":""},"message":"test violation","range":{"filename":"main.tf","start":{"line":1,"column":1},"end":{"line":1,"column":10}},"callers":[]}],"errors":[]}' }
+            $result = Invoke-TFLintCore -ConfigPath $script:TestConfigPath `
+                -OutputPath $script:TestOutputPath -TerraformDir $script:TestTerraformDir
+            $result | Should -Not -Be 0
+        }
+    }
+
+    Context 'output file creation' {
+        It 'Creates output file' {
+            Mock tflint { $global:LASTEXITCODE = 0; return '{"issues":[],"errors":[]}' }
+            Invoke-TFLintCore -ConfigPath $script:TestConfigPath `
+                -OutputPath $script:TestOutputPath -TerraformDir $script:TestTerraformDir
+            $script:TestOutputPath | Should -Exist
+        }
+    }
+}