gha-scanning-stages

gha-scanning-stages

Generates optional security and quality scanning jobs for inclusion in a GitHub Actions workflow. Each scanner is an independent job that depends on build. Scanning jobs are only emitted when the corresponding stages.*.enabled flag is true in .devops-agent.json. The Wiz scan is an exception — it runs as a step inside docker-build-push because it scans the built image, not the source code.

SonarQube

Action: sonarsource/sonarqube-scan-action@v3

Required secrets: SONAR_TOKEN, SONAR_HOST_URL

Special requirement: Checkout must include full history (fetch-depth: 0) so SonarQube can compute new-code metrics and blame annotations.

Enabled by: stages.sonarScan.enabled: true

sonar-scan:
  needs: build
  runs-on: [self-hosted, linux, x64]
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: SonarQube Scan
      uses: sonarsource/sonarqube-scan-action@v3
      env:
        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

Required GitHub Secrets:

Secret	Description
SONAR_TOKEN	SonarQube user token with Execute Analysis permission
SONAR_HOST_URL	Base URL of the SonarQube server (e.g., https://sonar.yourorg.internal)

The quality gate result is evaluated by the SonarQube server. If the quality gate fails, the action exits with a non-zero code and the job fails. Ensure the project is already registered in SonarQube and sonar-project.properties (or equivalent config) is present before enabling this stage.

Snyk

Action: snyk/actions/<language>@v1 — language-specific, not the generic snyk/actions@v1

Required secret: SNYK_TOKEN

Enabled by: stages.snykScan.enabled: true

Select the correct Snyk action variant based on the resolved language:

Language	Snyk Action
.NET	snyk/actions/dotnet@v1
Node.js	snyk/actions/node@v1
Java (Maven)	snyk/actions/maven@v1
Go	snyk/actions/golang@v1
Python	snyk/actions/python@v1

snyk-scan:
  needs: build
  runs-on: [self-hosted, linux, x64]
  steps:
    - uses: actions/checkout@v4
    - name: Snyk Security Scan
      uses: snyk/actions/dotnet@v1
      env:
        SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

Replace snyk/actions/dotnet@v1 with the appropriate language variant from the table above. To enforce a severity threshold (fail the job only on high or critical vulnerabilities), pass args: --severity-threshold=high in the with: block:

    - name: Snyk Security Scan
      uses: snyk/actions/dotnet@v1
      with:
        args: --severity-threshold=high
      env:
        SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

Required GitHub Secrets:

Secret	Description
SNYK_TOKEN	Snyk API token from the Snyk organization settings

Wiz

Command: wizcli docker scan (Bash step, not a marketplace action)

Required secrets: WIZ_CLIENT_ID, WIZ_CLIENT_SECRET

Enabled by: stages.wizScan.enabled: true

Unlike SonarQube and Snyk, the Wiz scan runs as a step inside docker-build-push after the Docker image is built, because it scans the image artifact directly. It is placed after the docker build step and before the docker push step so a failing scan blocks the push.

    - name: Wiz CLI Image Scan
      run: |
        wizcli docker scan \
          --image ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
          --policy "default-image-policy"
      env:
        WIZ_CLIENT_ID: ${{ secrets.WIZ_CLIENT_ID }}
        WIZ_CLIENT_SECRET: ${{ secrets.WIZ_CLIENT_SECRET }}

The Wiz policy name (default-image-policy) is configurable via stages.wizScan.policy in .devops-agent.json. If not set, use "default-image-policy" as the default. The wizcli binary must be available on the runner. Document runner prerequisites in team guidelines.

Required GitHub Secrets:

Secret	Description
WIZ_CLIENT_ID	Wiz service account client ID
WIZ_CLIENT_SECRET	Wiz service account client secret

Stage Emission Logic

At pipeline generation time, evaluate each enabled flag and build the job list accordingly:

if stages.sonarScan.enabled  → emit sonar-scan job
if stages.snykScan.enabled   → emit snyk-scan job
if stages.wizScan.enabled    → inject wiz step into docker-build-push

The docker-build-push job's needs: array is computed from whichever of the following are enabled:

needs:
  - build                     (always)
  - unit-test                 (if unitTest.enabled)
  - integration-test          (if integrationTest.enabled)
  - sonar-scan                (if sonarScan.enabled)
  - snyk-scan                 (if snykScan.enabled)

Wiz is not in needs: because it runs as a step inside the same job, not as a separate job.

Secrets Summary

Secret	Scanner	Notes
SONAR_TOKEN	SonarQube	Execute Analysis permission required
SONAR_HOST_URL	SonarQube	Full server URL including protocol
SNYK_TOKEN	Snyk	Organisation-level API token
WIZ_CLIENT_ID	Wiz	Service account client ID
WIZ_CLIENT_SECRET	Wiz	Service account client secret

All secrets must be stored in the GitHub repository or organisation secrets store. Never hardcode secret values in workflow YAML. See ## Secrets Management in defaults/coding-guidelines.md for rotation and naming conventions.