Sub-workflow versioning feature

.github/workflows/ci-main-pull-request.yml

@@ -347,7 +347,12 @@ on:
         description: 'Report Sonar test coverage and other metrics to Atlassian dashboard (Irfans QA dashboard)'
         required: false
         type: boolean
-        default: true     
+        default: true
+      quality-dashboard-version:
+        description: 'Version of quality dashboard workflow to use (e.g., main, v1.0.7)'
+        required: false
+        type: string
+        default: 'main'
       quality-product-name:
         description: 'Product name for quality reporting (Chef360, Courier, Inspec)'
         required: false
@@ -734,7 +739,7 @@ jobs:
   scc:
     name: 'Source code complexity checks'
     if: ${{ inputs.perform-complexity-checks == true }}
-    uses: chef/common-github-actions/.github/workflows/scc.yml@main
+    uses: chef/common-github-actions/.github/workflows/scc.yml@${{ inputs.scc-version }}
     needs: checkout
     with:
       outputfilename: ${{ inputs.scc-output-filename }}
@@ -859,7 +864,7 @@ jobs:
   run-trufflehog:
     name: 'Trufflehog scan'
     if: ${{ inputs.perform-trufflehog-scan }}
-    uses: chef/common-github-actions/.github/workflows/trufflehog.yml@main
+    uses: chef/common-github-actions/.github/workflows/trufflehog.yml@${{ inputs.trufflehog-version }}
     needs: checkout
     with:
       github-event-name: ${{ inputs.github-event-name }}
@@ -979,7 +984,7 @@ jobs:
   run-grype-image:
     name: 'Grype Docker image scan'
     if: ${{ inputs.perform-grype-image-scan }}
-    uses: chef/common-github-actions/.github/workflows/grype.yml@main
+    uses: chef/common-github-actions/.github/workflows/grype.yml@${{ inputs.grype-version }}
     needs: checkout
     secrets: inherit
     with:
@@ -990,7 +995,7 @@ jobs:
   run-grype-hab-package-scan:
     name: 'Grype scan Habitat packages from bldr.habitat.sh'
     if: ${{ inputs.perform-grype-hab-scan == true }}
-    uses: chef/common-github-actions/.github/workflows/grype-hab-package-scan.yml@main
+    uses: chef/common-github-actions/.github/workflows/grype-hab-package-scan.yml@${{ inputs.grype-hab-version }}
     needs: checkout
     secrets: inherit
     with:
@@ -1301,7 +1306,7 @@ jobs:
   BlackDuck-Polaris-SAST:
     name: 'BlackDuck Polaris SAST scan'
     if: ${{ inputs.perform-blackduck-polaris }}
-    uses: chef/common-github-actions/.github/workflows/polaris-sast.yml@main
+    uses: chef/common-github-actions/.github/workflows/polaris-sast.yml@${{ inputs.polaris-version }}
     needs: checkout
     secrets: inherit
     with:
@@ -1568,7 +1573,7 @@ jobs:
     name: 'Generating SBOM'
     #    Create software bill-of-materials (SBOM) using SPDX format
     if: ${{ inputs.generate-sbom == true }}
-    uses: chef/common-github-actions/.github/workflows/sbom.yml@main
+    uses: chef/common-github-actions/.github/workflows/sbom.yml@${{ inputs.sbom-version }}
     needs: checkout # TODO: fix set-application-version
     secrets: inherit
     with:
@@ -1599,7 +1604,7 @@ jobs:
       id-token: write
       contents: read
     if: ${{ inputs.report-to-atlassian-dashboard == true && success() }}
-    uses: chef/common-github-actions/.github/workflows/irfan-quality-dashboard.yml@main
+    uses: chef/common-github-actions/.github/workflows/irfan-quality-dashboard.yml@${{ inputs.quality-dashboard-version }}
     with:
       perform-build: ${{ inputs.build }} # was ${{ inputs.perform-sonar-build }}
       build-profile: ${{ inputs.build-profile }}

.github/workflows/stubs/ci-main-pull-request-stub.yml

@@ -38,18 +38,23 @@ jobs:
 
       # complexity-checks
       perform-complexity-checks: true
+      # scc-version: 'main'  # Version of SCC workflow (main, v1.0.7, etc.)
       # scc-output-filename: 'scc-output.txt'
       perform-language-linting: false    # Perform language-specific linting and pre-compilation checks
 
       # trufflehog secret scanning
       perform-trufflehog-scan: true
+      # trufflehog-version: 'main'  # Version of Trufflehog workflow (main, v1.0.7, etc.)
 
       # trivy dependency and container scanning
       perform-trivy-scan: true
+      # grype-version: 'main'  # Version of Grype workflow for source/image scans (main, v1.0.7, etc.)
+      # grype-hab-version: 'main'  # Version of Grype Habitat package scan workflow (main, v1.0.7, etc.)
 
       # BlackDuck SAST (Polaris) and SCA scans (requires a build or download to do SAST)
       # requires these secrets: POLARIS_SERVER_URL, POLARIS_ACCESS_TOKEN
       perform-blackduck-polaris: true
+      # polaris-version: 'main'  # Version of Polaris SAST workflow (main, v1.0.7, etc.)
       polaris-application-name: "Chef-Chef360"  # one of these: Chef-Agents, Chef-Automate, Chef-Chef360, Chef-Habitat, Chef-Infrastructure-Server, Chef-Shared-Services, Chef-Other, Chef-Non-Product
       polaris-project-name: ${{ github.event.repository.name }}
       # polaris-blackduck-executable: 'path/to/blackduck/binary'
@@ -82,6 +87,7 @@ jobs:
       perform-docker-scan: false  # scan Dockerfile and built images with Docker Scout or Trivy; see repo custom properties matching "container"
 
       # report to central developer dashboard
+      # quality-dashboard-version: 'main'  # Version of quality dashboard workflow (main, v1.0.7, etc.)
       report-to-atlassian-dashboard: false
       quality-product-name: 'Chef-360'   # product name for quality reporting, like Chef360, Courier, Inspec
       # quality-product-name: ${{ github.event.repository.name }}   # like 'Chef-360' - the product name for quality reporting, like Chef360, Courier, Inspec
@@ -105,6 +111,7 @@ jobs:
       publish-packages: false     # Publish packages (e.g., container from Dockerfile to ECR, go-releaser binary to releases page, omnibus to artifactory, gems, choco, homebrew, other app stores)
 
       # generate and export Software Bill of Materials (SBOM) in various formats
+      # sbom-version: 'main'  # Version of SBOM workflow (main, v1.0.7, etc.)
       generate-sbom: true
       export-github-sbom: true      # SPDX JSON artifact on job instance  
       perform-blackduck-sca-scan: true # combined with generate sbom & generate github-sbom, also needs version above

HOW-TO-USE.md

@@ -48,6 +48,12 @@ jobs:
     with:   
       visibility: ${{ github.event.repository.visibility }}
       language: 'go'  # go, ruby, rust
+
+      # Optionally pin individual scan versions (all default to 'main')
+      # trufflehog-version: 'v1.0.7'
+      # grype-version: 'v1.0.7'
+      # sbom-version: 'v1.0.7'
+
       perform-complexity-checks: true
       perform-trufflehog-scan: true
       perform-trivy-scan: true
@@ -102,6 +108,43 @@ Tags follow semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}`
 
 When code is merged to `main` in `common-github-actions`, a new patch tag is automatically created via the `create-release-tag.yml` workflow. Manual version bumps can be triggered via workflow dispatch.
 
+### Sub-Workflow Versioning (NEW)
+
+**Each security scan can be pinned to its own version independently**, giving you fine-grained control over which scan versions to use:
+
+```yaml
+jobs:
+  ci:
+    uses: chef/common-github-actions/.github/workflows/[email protected]
+    with:
+      # Pin individual scan versions
+      scc-version: 'v1.0.7'              # Use stable SCC
+      trufflehog-version: 'v1.0.7'       # Use stable TruffleHog
+      grype-version: 'main'              # Use latest Grype
+      grype-hab-version: 'v1.0.6'        # Use older Habitat scan
+      polaris-version: 'v1.0.7'          # Use stable Polaris
+      sbom-version: 'v1.0.7'             # Use stable SBOM
+      quality-dashboard-version: 'main'  # Use latest dashboard
+```
+
+**Benefits:**
+- Pin versions that work well with your project
+- Update individual scans without affecting others
+- Test new scan versions without full pipeline upgrade
+- Avoid breaking changes in production workflows
+- Roll back specific scans if issues arise
+
+**Available Version Inputs:**
+- `scc-version` - Source code complexity checks
+- `trufflehog-version` - Secret scanning
+- `grype-version` - Grype image/source scanning
+- `grype-hab-version` - Grype Habitat package scanning
+- `polaris-version` - BlackDuck Polaris SAST
+- `sbom-version` - SBOM generation and BlackDuck SCA
+- `quality-dashboard-version` - Quality dashboard reporting
+
+**Default:** All sub-workflows default to `'main'` if not specified.
+
 ---
 
 ## Available Workflows
@@ -166,6 +209,12 @@ jobs:
       version: '1.0.0'
       build-profile: 'cli'
 
+      # Pin scan versions for stability (optional)
+      trufflehog-version: 'v1.0.7'
+      grype-version: 'v1.0.7'
+      polaris-version: 'v1.0.7'
+      sbom-version: 'v1.0.7'
+
       # Code Quality
       perform-complexity-checks: true
       perform-language-linting: true
@@ -259,6 +308,9 @@ jobs:
       visibility: ${{ github.event.repository.visibility }}
       language: 'go'
 
+      # Use specific versions for critical scans
+      trufflehog-version: 'v1.0.7'  # Pin to stable version
+
       # Disable everything except security scans
       perform-complexity-checks: false
       perform-language-linting: false

PIPELINE-REFERENCE.md

@@ -6,6 +6,56 @@ This document provides comprehensive information about the security and quality
 
 ## Pipeline Overview
 
+### Sub-Workflow Versioning
+
+**NEW in v1.0.7+**: Each security scan workflow can be pinned to a specific version independently. This allows you to:
+
+- **Pin stable versions** that work with your project
+- **Update incrementally** - test one scan at a time
+- **Avoid breaking changes** - stay on known-good versions
+- **Roll back easily** - revert specific scans if needed
+
+**Version Control Strategy:**
+
+```yaml
+# Example: Mix stable and latest versions
+jobs:
+  ci:
+    uses: chef/common-github-actions/.github/workflows/[email protected]
+    with:
+      # Production-critical scans: pin to tested versions
+      trufflehog-version: 'v1.0.7'
+      polaris-version: 'v1.0.7'
+      sbom-version: 'v1.0.7'
+
+      # Non-blocking scans: use latest
+      scc-version: 'main'
+      grype-version: 'main'
+
+      # Your scan configurations...
+      perform-trufflehog-scan: true
+      perform-blackduck-polaris: true
+      generate-sbom: true
+```
+
+**Available Version Inputs:**
+
+| Input | Workflow | Default | Description |
+|-------|----------|---------|-------------|
+| `scc-version` | scc.yml | `main` | Source code complexity |
+| `trufflehog-version` | trufflehog.yml | `main` | Secret scanning |
+| `grype-version` | grype.yml | `main` | Image/source scanning |
+| `grype-hab-version` | grype-hab-package-scan.yml | `main` | Habitat package scanning |
+| `polaris-version` | polaris-sast.yml | `main` | BlackDuck Polaris SAST |
+| `sbom-version` | sbom.yml | `main` | SBOM + BlackDuck SCA |
+| `quality-dashboard-version` | irfan-quality-dashboard.yml | `main` | Quality reporting |
+
+**Recommendation:** Pin to specific versions (e.g., `v1.0.7`) for production repositories. Use `main` for development/testing repositories to get latest features.
+
+---
+
+## Pipeline Overview
+
 ```mermaid
 graph TD
     Start([Pull Request/Push Event]) --> PreCheck[precompilation-checks]
@@ -70,16 +120,20 @@ graph TD
 
 ```mermaid
 graph LR
-    A[scc Job] -->|calls| B[scc.yml]
+    A[scc Job] -->|calls| B[scc.yml@version]
     B -->|requires| C[Variables]
 
     C -->|input| D[outputfilename: string]
+    C -->|version| E[scc-version: string]
 
     style A fill:#e1f5ff
     style B fill:#d4edff
 ```
 
-**Workflow File:** `chef/common-github-actions/.github/workflows/scc.yml`
+**Workflow File:** `chef/common-github-actions/.github/workflows/scc.yml@{version}`
+
+**Version Input:**
+- `scc-version` (string) - Version of SCC workflow to use (e.g., 'main', 'v1.0.7'), default: 'main'
 
 **Required Variables:**
 - `outputfilename` (string) - Name of the SCC complexity output file artifact, default: 'scc-complexity'
@@ -143,16 +197,20 @@ graph LR
 
 ```mermaid
 graph LR
-    A[run-trufflehog Job] -->|calls| B[trufflehog.yml]
+    A[run-trufflehog Job] -->|calls| B[trufflehog.yml@version]
     B -->|requires| C[Variables]
 
     C -->|no inputs| D[None Required]
+    C -->|version| E[trufflehog-version: string]
 
     style A fill:#ffe1e1
     style B fill:#ffd4d4
 ```
 
-**Workflow File:** `chef/common-github-actions/.github/workflows/trufflehog.yml`
+**Workflow File:** `chef/common-github-actions/.github/workflows/trufflehog.yml@{version}`
+
+**Version Input:**
+- `trufflehog-version` (string) - Version of Trufflehog workflow to use (e.g., 'main', 'v1.0.7'), default: 'main'
 
 **Required Variables:**
 - None (inherits secrets automatically)
@@ -228,17 +286,21 @@ graph LR
 
 ```mermaid
 graph LR
-    A[BlackDuck-Polaris-SAST Job] -->|inline steps| B[Inline Implementation]
+    A[BlackDuck-Polaris-SAST Job] -->|calls| B[polaris-sast.yml@version]
     B -->|requires| C[Variables]
 
     C -->|secrets| D[POLARIS_SERVER_URL<br/>POLARIS_ACCESS_TOKEN]
     C -->|inputs| E[polaris-application-name<br/>polaris-project-name<br/>polaris-working-directory<br/>polaris-config-path<br/>polaris-coverity-config-path<br/>polaris-coverity-build-command<br/>polaris-coverity-clean-command<br/>polaris-coverity-args<br/>polaris-detect-search-depth<br/>polaris-detect-args<br/>polaris-assessment-mode<br/>wait-for-scan]
+    C -->|version| F[polaris-version: string]
 
     style A fill:#ffe1e1
     style B fill:#ffd4d4
 ```
 
-**Workflow File:** Inline implementation (no separate workflow)
+**Workflow File:** `chef/common-github-actions/.github/workflows/polaris-sast.yml@{version}`
+
+**Version Input:**
+- `polaris-version` (string) - Version of Polaris SAST workflow to use (e.g., 'main', 'v1.0.7'), default: 'main'
 
 **Required Secrets:**
 - `POLARIS_SERVER_URL` - BlackDuck Polaris server URL
@@ -429,12 +491,17 @@ graph LR
 
     C -->|secrets| D[HAB_PUBLIC_BLDR_PAT]
     C -->|inputs| E[publish-habitat-hab_package<br/>publish-habitat-hab_version<br/>publish-habitat-hab_release<br/>publish-habitat-hab_channel<br/>publish-habitat-hab_auth_token]
+    C -->|version| F[grype-version or grype-hab-version]
 
     style A fill:#ffe1e1
     style B fill:#ffd4d4
 ```
 
-**Workflow File:** Inline implementation
+**Workflow File:** Inline implementation (for inline scans) or `grype.yml@{version}` / `grype-hab-package-scan.yml@{version}`
+
+**Version Inputs:**
+- `grype-version` (string) - Version of Grype workflow for image/source scans, default: 'main'
+- `grype-hab-version` (string) - Version of Grype Habitat package scan workflow, default: 'main'
 
 **Required Secrets:**
 - `HAB_PUBLIC_BLDR_PAT` - Habitat Builder personal access token (fallback)
@@ -544,17 +611,21 @@ graph LR
 
 ```mermaid
 graph LR
-    A[generate-sbom Job] -->|calls| B[sbom.yml]
+    A[generate-sbom Job] -->|calls| B[sbom.yml@version]
     B -->|requires| C[Variables]
 
     C -->|secrets| D[BLACKDUCK_SBOM_URL<br/>BLACKDUCK_SCA_TOKEN]
     C -->|inputs| E[version<br/>export-github-sbom<br/>perform-blackduck-sca-scan<br/>blackduck-project-group-name<br/>blackduck-project-name<br/>generate-msft-sbom<br/>license_scout<br/>go-private-modules]
+    C -->|version| F[sbom-version: string]
 
     style A fill:#e1ffe1
     style B fill:#c5f5c5
 ```
 
-**Workflow File:** `chef/common-github-actions/.github/workflows/sbom.yml`
+**Workflow File:** `chef/common-github-actions/.github/workflows/sbom.yml@{version}`
+
+**Version Input:**
+- `sbom-version` (string) - Version of SBOM workflow to use (e.g., 'main', 'v1.0.7'), default: 'main'
 
 **Required Secrets:**
 - `BLACKDUCK_SBOM_URL` - BlackDuck SCA server URL
@@ -600,16 +671,20 @@ graph LR
 
 ```mermaid
 graph LR
-    A[quality-dashboard Job] -->|calls| B[irfan-quality-dashboard.yml]
+    A[quality-dashboard Job] -->|calls| B[irfan-quality-dashboard.yml@version]
     B -->|requires| C[Variables]
 
     C -->|inputs| D[perform-build<br/>build-profile<br/>language<br/>report-unit-test-coverage<br/>report-to-atlassian-dashboard<br/>quality-product-name<br/>quality-sonar-app-name<br/>quality-testing-type<br/>quality-service-name<br/>quality-junit-report<br/>visibility<br/>go-private-modules<br/>udf1, udf2, udf3]
+    C -->|version| E[quality-dashboard-version: string]
 
     style A fill:#f0e1ff
     style B fill:#e0c5ff
 ```
 
-**Workflow File:** `chef/common-github-actions/.github/workflows/irfan-quality-dashboard.yml`
+**Workflow File:** `chef/common-github-actions/.github/workflows/irfan-quality-dashboard.yml@{version}`
+
+**Version Input:**
+- `quality-dashboard-version` (string) - Version of quality dashboard workflow to use (e.g., 'main', 'v1.0.7'), default: 'main'
 
 **Required Variables:**
 - `perform-build` (boolean) - Whether build was performed