initial commit

Change-Id: I5f624b221545283dafa1ca30bef9b8b722fcf0c7

.gitea/workflows/build-push.yml

@@ -0,0 +1,84 @@
+name: Build and Push to ACR
+
+on:
+  push:
+    branches: [ dev ]
+  workflow_dispatch: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  AZURE_FEDERATED_TOKEN_FILE: /var/run/secrets/azure/tokens/azure-identity-token
+
+jobs:
+  build:
+    name: Build and Push
+    runs-on: ubuntu-latest
+    if: >-
+      github.ref != 'refs/heads/main' && (
+        github.event_name == 'workflow_dispatch' ||
+        (github.event_name == 'push' && github.event.before != '0000000000000000000000000000000000000000')
+      )
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Azure CLI
+        run: |
+          command -v az &>/dev/null || curl -sL https://aka.ms/InstallAzureCLIDeb | bash
+
+      - name: Install Docker CLI
+        run: |
+          command -v docker &>/dev/null || (apt-get update -qq && apt-get install -y docker.io)
+          docker --version
+
+      - name: Azure login (OIDC)
+        run: |
+          az login \
+            --service-principal \
+            --username "$AZURE_CLIENT_ID" \
+            --tenant "$AZURE_TENANT_ID" \
+            --federated-token "$(cat $AZURE_FEDERATED_TOKEN_FILE)"
+          echo "✓ Azure login successful"
+
+      - name: Get ACR details
+        run: |
+          ACR_NAME=$(az acr list --query "[0].name" -o tsv)
+          ACR_NAME="${ACR_NAME:-bstagecjotdevacr}"
+          echo "ACR_NAME=$ACR_NAME" >> $GITHUB_ENV
+          echo "ACR_LOGIN_SERVER=${ACR_NAME}.azurecr.io" >> $GITHUB_ENV
+          echo "✓ Using ACR: ${ACR_NAME}.azurecr.io"
+
+      - name: ACR Login
+        run: |
+          ACR_TOKEN=$(az acr login --name "$ACR_NAME" --expose-token --output tsv --query accessToken)
+          docker login "$ACR_LOGIN_SERVER" \
+            --username 00000000-0000-0000-0000-000000000000 \
+            --password "$ACR_TOKEN"
+          echo "✓ ACR login successful"
+
+      - name: Build and Push Docker image
+        run: |
+          IMAGE_TAG="${{ gitea.sha }}"
+          IMAGE_FULL="${ACR_LOGIN_SERVER}/lint-enforcement-v3:${IMAGE_TAG}"
+          IMAGE_LATEST="${ACR_LOGIN_SERVER}/lint-enforcement-v3:latest"
+          docker build -t "$IMAGE_FULL" -t "$IMAGE_LATEST" .
+          docker push "$IMAGE_FULL"
+          docker push "$IMAGE_LATEST"
+          echo "IMAGE_FULL=$IMAGE_FULL" >> $GITHUB_ENV
+          echo "✓ Pushed: $IMAGE_FULL"
+
+      - name: Build Summary
+        run: |
+          echo "### ✅ Build Successful" >> $GITHUB_STEP_SUMMARY
+          echo "| | |" >> $GITHUB_STEP_SUMMARY
+          echo "|---|---|" >> $GITHUB_STEP_SUMMARY
+          echo "| **Service** | lint-enforcement-v3 |" >> $GITHUB_STEP_SUMMARY
+          echo "| **Commit** | ${{ gitea.sha }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| **Image** | $IMAGE_FULL |" >> $GITHUB_STEP_SUMMARY

.gitea/workflows/integration-test.yml

@@ -0,0 +1,138 @@
+
+name: Integration Test
+
+on:
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ── Job 1: Platform Conformance ───────────────────────────────────────────
+  platform-check:
+    name: Platform Conformance
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate catalog-info.yaml
+        run: |
+          if [ ! -f catalog-info.yaml ]; then
+            echo "✗ catalog-info.yaml not found"
+            exit 1
+          fi
+          python3 -c "import yaml; list(yaml.safe_load_all(open('catalog-info.yaml')))" 2>/dev/null \
+            || (pip install pyyaml -q && python3 -c "import yaml; list(yaml.safe_load_all(open('catalog-info.yaml')))")
+          echo "✓ catalog-info.yaml is valid YAML"
+
+      - name: Check platform files
+        run: |
+          ERRORS=0
+          for f in catalog-info.yaml; do
+            if [ ! -f "$f" ]; then
+              echo "✗ Missing: $f"
+              ERRORS=$((ERRORS+1))
+            else
+              echo "✓ Found: $f"
+            fi
+          done
+          if [ $ERRORS -gt 0 ]; then exit 1; fi
+
+  # ── Job 2: Unit Tests + Container Smoke ───────────────────────────────────
+  smoke-test:
+    name: Unit Tests + Container Smoke
+    runs-on: ubuntu-latest
+    needs: platform-check
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Free disk space
+        run: |
+          docker system prune -f 2>/dev/null || true
+          df -h / 2>/dev/null || true
+
+      - name: Install Docker CLI
+        run: command -v docker &>/dev/null || (apt-get update -qq && apt-get install -y docker.io)
+
+      - name: Build container image
+        run: |
+          if [ -f Dockerfile ]; then
+            docker build -t ci-image:test .
+          else
+            echo "No Dockerfile found — skipping container smoke test"
+            echo "SKIP_SMOKE=true" >> $GITHUB_ENV
+          fi
+
+      - name: Start service and wait for health
+        if: env.SKIP_SMOKE != 'true'
+        run: |
+          CONTAINER_NAME="ci-${GITHUB_RUN_ID}"
+          PORT="${CONTAINER_PORT:-8080}"
+          HEALTH_PATH="${HEALTH_ENDPOINT:-/health}"
+          echo "CONTAINER_NAME=${CONTAINER_NAME}" >> $GITHUB_ENV
+          echo "CONTAINER_PORT=${PORT}" >> $GITHUB_ENV
+          echo "HEALTH_PATH=${HEALTH_PATH}" >> $GITHUB_ENV
+
+          docker run -d --name "${CONTAINER_NAME}" -e OTEL_SDK_DISABLED=true ci-image:test
+
+          for i in $(seq 1 10); do
+            CONTAINER_IP=$(docker inspect "${CONTAINER_NAME}" --format '{{.NetworkSettings.IPAddress}}' 2>/dev/null)
+            [ -n "${CONTAINER_IP}" ] && break
+            sleep 1
+          done
+          echo "CONTAINER_IP=${CONTAINER_IP}" >> $GITHUB_ENV
+
+          echo "Waiting for ${HEALTH_PATH} on ${CONTAINER_IP}:${PORT} (up to 180s)..."
+          DEADLINE=$(($(date +%s) + 180))
+          while true; do
+            if curl -sf "http://${CONTAINER_IP}:${PORT}${HEALTH_PATH}" >/dev/null 2>&1; then
+              break
+            fi
+            if [ $(date +%s) -ge $DEADLINE ]; then
+              echo "Timeout waiting for health check"
+              docker logs "${CONTAINER_NAME}" 2>&1 | tail -30
+              exit 1
+            fi
+            if ! docker ps --filter "name=${CONTAINER_NAME}" --format '{{.Status}}' | grep -q Up; then
+              echo "Container exited:"
+              docker logs "${CONTAINER_NAME}" 2>&1 | tail -30
+              exit 1
+            fi
+            echo "  still waiting..."; sleep 3
+          done
+          echo "✓ Service healthy at ${CONTAINER_IP}:${PORT}${HEALTH_PATH}"
+
+      - name: Validate health response
+        if: env.SKIP_SMOKE != 'true'
+        run: |
+          curl -sf "http://${CONTAINER_IP}:${CONTAINER_PORT}${HEALTH_PATH}" > /tmp/health.json
+          echo "Health response:"
+          cat /tmp/health.json
+          echo ""
+          echo "✓ Container smoke test: PASSED"
+
+      - name: Cleanup
+        if: always()
+        run: docker rm -f "ci-${GITHUB_RUN_ID}" 2>/dev/null || true
+
+      - name: Post commit status
+        if: always()
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          JOB_STATUS: ${{ job.status }}
+        run: |
+          STATE=$([[ "$JOB_STATUS" == "success" ]] && echo "success" || echo "failure")
+          DESC=$([[ "$STATE" == "success" ]] && echo "All checks passed" || echo "Some checks failed")
+          curl -sf -X POST \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/statuses/${GITHUB_SHA}" \
+            -d "{\"state\":\"${STATE}\",\"context\":\"Integration Test / Unit Tests + Container Smoke (workflow_dispatch)\",\"description\":\"${DESC}\"}" \
+            || true

.gitea/workflows/pr-lint-gate.yml

@@ -0,0 +1,219 @@
+
+name: PR Lint and Validation Gate
+
+on:
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  yaml-and-whitespace:
+    name: YAML and Whitespace
+    runs-on: ubuntu-latest
+    outputs:
+      elapsed_seconds: ${{ steps.elapsed.outputs.seconds }}
+    steps:
+      - name: Start timer
+        run: echo "START_TS=$(date +%s)" >> "$GITHUB_ENV"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install yamllint
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install yamllint
+
+      - name: Run yamllint
+        run: |
+          yamllint -d "{extends: default, rules: {line-length: {max: 180}, truthy: disable}}" .
+
+      - name: Check trailing whitespace
+        run: |
+          if git ls-files -z | xargs -0 -I{} grep -nH -E "[[:blank:]]+$" "{}" \
+            --exclude="*.md" --exclude="*.svg"; then
+            echo "Trailing whitespace found"
+            exit 1
+          fi
+
+      - name: Capture duration
+        id: elapsed
+        if: always()
+        run: |
+          end_ts=$(date +%s)
+          start_ts=${START_TS:-$end_ts}
+          echo "seconds=$((end_ts - start_ts))" >> "$GITHUB_OUTPUT"
+
+  helm-lint:
+    name: Helm Lint
+    runs-on: ubuntu-latest
+    outputs:
+      elapsed_seconds: ${{ steps.elapsed.outputs.seconds }}
+    steps:
+      - name: Start timer
+        run: echo "START_TS=$(date +%s)" >> "$GITHUB_ENV"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Helm
+        uses: azure/setup-helm@v4
+
+      - name: Lint all charts
+        run: |
+          mapfile -t charts < <(find . -type f -name Chart.yaml -print)
+          if [ -z "${charts[0]:-}" ]; then
+            echo "No Helm charts found; skipping"
+            exit 0
+          fi
+
+          failed=0
+          for chart in "${charts[@]}"; do
+            chart_dir="$(dirname "$chart")"
+            echo "Linting ${chart_dir}"
+            if ! helm lint "$chart_dir"; then
+              failed=1
+            fi
+          done
+          exit $failed
+
+      - name: Capture duration
+        id: elapsed
+        if: always()
+        run: |
+          end_ts=$(date +%s)
+          start_ts=${START_TS:-$end_ts}
+          echo "seconds=$((end_ts - start_ts))" >> "$GITHUB_OUTPUT"
+
+  terraform-lint:
+    name: Terraform Validate and TFLint
+    runs-on: ubuntu-latest
+    outputs:
+      elapsed_seconds: ${{ steps.elapsed.outputs.seconds }}
+    steps:
+      - name: Start timer
+        run: echo "START_TS=$(date +%s)" >> "$GITHUB_ENV"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Install TFLint
+        run: |
+          curl -s https://raw.githubusercontent.com/terraform-linters/tflint/master/install_linux.sh | bash
+
+      - name: Validate Terraform directories
+        run: |
+          mapfile -t tf_dirs < <(find . -type f -name "*.tf" -exec dirname {} \; | sort -u)
+          if [ -z "${tf_dirs[0]:-}" ]; then
+            echo "No Terraform files found; skipping"
+            exit 0
+          fi
+
+          failed=0
+          for dir in "${tf_dirs[@]}"; do
+            echo "Validating ${dir}"
+            (
+              cd "$dir"
+              terraform init -backend=false -input=false -no-color
+              terraform validate -no-color
+              tflint --chdir .
+            ) || failed=1
+          done
+          exit $failed
+
+      - name: Capture duration
+        id: elapsed
+        if: always()
+        run: |
+          end_ts=$(date +%s)
+          start_ts=${START_TS:-$end_ts}
+          echo "seconds=$((end_ts - start_ts))" >> "$GITHUB_OUTPUT"
+
+  policy-and-deps:
+    name: Policy and Dependency Scan
+    runs-on: ubuntu-latest
+    outputs:
+      elapsed_seconds: ${{ steps.elapsed.outputs.seconds }}
+    steps:
+      - name: Start timer
+        run: echo "START_TS=$(date +%s)" >> "$GITHUB_ENV"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Checkov
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install checkov
+
+      - name: Run Checkov (Kubernetes)
+        run: |
+          checkov -d . --framework kubernetes --skip-path "examples/default/rendered/.*" --quiet
+
+      - name: npm audit (if package.json exists)
+        run: |
+          if [ -f package.json ]; then
+            npm install --no-audit --no-fund
+            npm audit --audit-level=high
+          else
+            echo "No package.json found; skipping npm audit"
+          fi
+
+      - name: Maven dependency-check (if pom.xml exists)
+        run: |
+          if [ -f pom.xml ]; then
+            mvn -B org.owasp:dependency-check-maven:check
+          else
+            echo "No pom.xml found; skipping Maven dependency-check"
+          fi
+
+      - name: Capture duration
+        id: elapsed
+        if: always()
+        run: |
+          end_ts=$(date +%s)
+          start_ts=${START_TS:-$end_ts}
+          echo "seconds=$((end_ts - start_ts))" >> "$GITHUB_OUTPUT"
+
+  runtime-slo:
+    name: Runtime SLO (< 3 min)
+    if: always()
+    needs:
+      - yaml-and-whitespace
+      - helm-lint
+      - terraform-lint
+      - policy-and-deps
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enforce suite runtime budget
+        run: |
+          y=${{ needs.yaml-and-whitespace.outputs.elapsed_seconds || 0 }}
+          h=${{ needs.helm-lint.outputs.elapsed_seconds || 0 }}
+          t=${{ needs.terraform-lint.outputs.elapsed_seconds || 0 }}
+          p=${{ needs.policy-and-deps.outputs.elapsed_seconds || 0 }}
+
+          # Jobs run in parallel; full-suite wall-clock is approximated by max(job runtimes).
+          suite=$y
+          [ $h -gt $suite ] && suite=$h
+          [ $t -gt $suite ] && suite=$t
+          [ $p -gt $suite ] && suite=$p
+
+          echo "## PR Lint Gate Runtime" >> "$GITHUB_STEP_SUMMARY"
+          echo "- YAML and Whitespace: ${y}s" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Helm Lint: ${h}s" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Terraform Validate and TFLint: ${t}s" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Policy and Dependency Scan: ${p}s" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Full suite (parallel max): ${suite}s" >> "$GITHUB_STEP_SUMMARY"
+
+          if [ $suite -gt 180 ]; then
+            echo "Runtime SLO exceeded: ${suite}s > 180s"
+            exit 1
+          fi
+

.gitea/workflows/security-scan.yml

@@ -0,0 +1,164 @@
+name: Security Scanning
+
+on:
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch: {}
+
+env:
+  TRIVY_VERSION: "0.69.3"
+  GITLEAKS_VERSION: "8.18.4"
+  COMPONENT_ID: lint-enforcement-v3
+
+jobs:
+  # ─────────────────────────────────────────────
+  # 1. FILESYSTEM & DEPENDENCY SCAN
+  #    Trivy auto-detects lockfiles (pom.xml,
+  #    package-lock.json, go.sum, requirements.txt, etc.)
+  #    and scans for vulns, secrets, and misconfigs.
+  # ─────────────────────────────────────────────
+  trivy-scan:
+    name: Trivy — Filesystem & Dependency Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Install Trivy
+        run: |
+          set -e
+          mkdir -p $HOME/.local/bin
+          curl -sSfL "https://github.com/aquasecurity/trivy/releases/download/v${{ env.TRIVY_VERSION }}/trivy_${{ env.TRIVY_VERSION }}_Linux-64bit.tar.gz" \
+            | tar -xz -C $HOME/.local/bin trivy
+          chmod +x $HOME/.local/bin/trivy
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Run Trivy filesystem scan
+        run: |
+          $HOME/.local/bin/trivy fs \
+            --exit-code 0 \
+            --severity HIGH,CRITICAL \
+            --format sarif \
+            --output trivy-results.sarif \
+            --scanners vuln,secret,misconfig \
+            --dependency-tree \
+            .
+
+      - name: Upload SARIF report
+        uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: trivy-sarif
+          path: trivy-results.sarif
+          retention-days: 30
+
+      - name: Print human-readable summary
+        run: |
+          $HOME/.local/bin/trivy fs \
+            --exit-code 0 \
+            --severity MEDIUM,HIGH,CRITICAL \
+            --format table \
+            --scanners vuln,secret,misconfig \
+            .
+
+      - name: Enforce quality gate (CRITICAL — report only)
+        run: |
+          $HOME/.local/bin/trivy fs \
+            --exit-code 0 \
+            --severity CRITICAL \
+            --scanners vuln,misconfig \
+            .
+
+  # ─────────────────────────────────────────────
+  # 2. SECRET SCAN — detect leaked credentials
+  #    across full git history.
+  # ─────────────────────────────────────────────
+  gitleaks-scan:
+    name: Gitleaks — Secret Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source (full history)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Install Gitleaks binary directly — the GitHub Action
+      # relies on GITHUB_TOKEN which is unavailable on Gitea Act runners.
+      - name: Install Gitleaks
+        run: |
+          set -e
+          mkdir -p $HOME/.local/bin
+          curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${{ env.GITLEAKS_VERSION }}/gitleaks_${{ env.GITLEAKS_VERSION }}_linux_x64.tar.gz" \
+            | tar -xz -C $HOME/.local/bin gitleaks
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Run Gitleaks
+        run: |
+          $HOME/.local/bin/gitleaks detect \
+            --source . \
+            --report-format sarif \
+            --report-path gitleaks-results.sarif \
+            --exit-code 1 \
+            --log-level warn
+
+      - name: Upload SARIF report
+        uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: gitleaks-sarif
+          path: gitleaks-results.sarif
+          retention-days: 30
+
+  # ─────────────────────────────────────────────
+  # 3. SUMMARY — aggregate all SARIF reports
+  # ─────────────────────────────────────────────
+  security-summary:
+    name: Security Summary
+    needs:
+      - trivy-scan
+      - gitleaks-scan
+    runs-on: ubuntu-latest
+    if: always()
+
+    steps:
+      - name: Download Trivy SARIF
+        uses: actions/download-artifact@v3
+        with:
+          name: trivy-sarif
+          path: sarif-reports/
+        continue-on-error: true
+
+      - name: Download Gitleaks SARIF
+        uses: actions/download-artifact@v3
+        with:
+          name: gitleaks-sarif
+          path: sarif-reports/
+        continue-on-error: true
+
+      - name: List collected reports
+        run: ls -lh sarif-reports/ || echo "No reports found"
+
+      - name: Generate summary
+        run: |
+          echo "## Security Scan Results — ${{ env.COMPONENT_ID }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Report | Size |" >> $GITHUB_STEP_SUMMARY
+          echo "|--------|------|" >> $GITHUB_STEP_SUMMARY
+          for f in sarif-reports/*.sarif; do
+            [ -e "$f" ] || continue
+            name=$(basename "$f")
+            size=$(du -sh "$f" | cut -f1)
+            echo "| $name | $size |" >> $GITHUB_STEP_SUMMARY
+          done
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Commit: \`${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "Branch: \`${{ github.ref_name }}\`" >> $GITHUB_STEP_SUMMARY
+
+      - name: Bundle all SARIF reports
+        uses: actions/upload-artifact@v3
+        with:
+          name: all-sarif-reports
+          path: sarif-reports/
+          retention-days: 90

.gitea/workflows/sonar.yaml

@@ -0,0 +1,227 @@
+
+name: SonarQube Analysis
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: ${{ gitea.workflow }}-${{ gitea.ref }}
+  cancel-in-progress: true
+
+jobs:
+  sonarqube:
+    name: Build, Test & Analyse
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    env:
+      SONAR_PROJECT_KEY: lint-enforcement-v3
+      SONAR_ADMIN_TOKEN: ${{ secrets.SONAR_ADMIN_TOKEN }}
+      SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+      BACKSTAGE_CLEANUP_TOKEN: ${{ secrets.BACKSTAGE_CLEANUP_TOKEN }}
+      # NOTE: the BACKSTAGE_URL is derived from the environment that triggered the workflow.
+      #       This allows the same workflow to be used across different environments (e.g., dev, staging, prod) without hardcoding environment-specific URLs or requiring additional secrets configuration.
+      #       It is utilised to send a notification to Backstage in case the quality gate fails, so that the relevant teams are alerted and can take action
+      BACKSTAGE_URL: https://dev-shraavya.backstage.kyndemo.live
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+
+      - name: Make Maven wrapper executable
+        run: chmod +x mvnw
+
+      - name: Cache Maven packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.m2/repository
+          key: maven-${{ runner.os }}-${{ hashFiles('**/pom.xml') }}
+          restore-keys: maven-${{ runner.os }}-
+
+      - name: Cache SonarQube analysis data
+        uses: actions/cache@v4
+        with:
+          path: ~/.sonar/cache
+          key: sonar-${{ runner.os }}-${{ hashFiles('**/pom.xml') }}
+          restore-keys: sonar-${{ runner.os }}-
+
+      - name: Validate required secrets
+        run: |
+          [[ -n "$SONAR_ADMIN_TOKEN" ]] || { echo "::error::SONAR_ADMIN_TOKEN is not set"; exit 1; }
+          [[ -n "$SONAR_HOST_URL" ]]    || { echo "::error::SONAR_HOST_URL is not set"; exit 1; }
+          [[ -n "$SONAR_PROJECT_KEY" ]] || { echo "::error::SONAR_PROJECT_KEY is not set"; exit 1; }
+
+          SONAR_HOST_URL="${SONAR_HOST_URL%/}"
+
+          AUTH_RESPONSE=$(curl -s -o /tmp/sonar-auth-response.json -w "%{http_code}" \
+            -u "${SONAR_ADMIN_TOKEN}:" \
+            "${SONAR_HOST_URL}/api/authentication/validate")
+
+          if [[ "$AUTH_RESPONSE" != "200" ]]; then
+            echo "::error::SonarQube is unreachable or returned HTTP ${AUTH_RESPONSE} — check SONAR_HOST_URL"
+            exit 1
+          fi
+
+          TOKEN_VALID=$(jq -r '.valid' /tmp/sonar-auth-response.json 2>/dev/null || echo "false")
+          if [[ "$TOKEN_VALID" != "true" ]]; then
+            echo "::error::SONAR_ADMIN_TOKEN is invalid or has been revoked (SonarQube returned valid=false)"
+            exit 1
+          fi
+
+          echo "✅ SONAR_ADMIN_TOKEN verified against ${SONAR_HOST_URL}"
+
+      - name: Bootstrap SonarQube project and generate scan token
+        id: sonar-bootstrap
+        run: |
+          PROJECT_COUNT=$(curl -sf \
+            -u "${SONAR_ADMIN_TOKEN}:" \
+            "${SONAR_HOST_URL}/api/projects/search?projects=${SONAR_PROJECT_KEY}" \
+            | jq '.paging.total')
+
+          if [[ "$PROJECT_COUNT" == "0" ]]; then
+            echo "Project '${SONAR_PROJECT_KEY}' not found — creating it..."
+            curl -sf -X POST \
+              -u "${SONAR_ADMIN_TOKEN}:" \
+              "${SONAR_HOST_URL}/api/projects/create" \
+              --data-urlencode "name=${SONAR_PROJECT_KEY}" \
+              --data-urlencode "project=${SONAR_PROJECT_KEY}" \
+              --data-urlencode "mainBranch=main" \
+              --data-urlencode "visibility=private"
+            echo "✅ Project created."
+          else
+            echo "✅ Project '${SONAR_PROJECT_KEY}' already exists — skipping creation."
+          fi
+
+          TOKEN_NAME="gitea-scan-${SONAR_PROJECT_KEY}"
+          curl -sf -X POST \
+            -u "${SONAR_ADMIN_TOKEN}:" \
+            "${SONAR_HOST_URL}/api/user_tokens/revoke" \
+            --data-urlencode "name=${TOKEN_NAME}" \
+            > /dev/null 2>&1 || true
+
+          SCAN_TOKEN=$(curl -sf -X POST \
+            -u "${SONAR_ADMIN_TOKEN}:" \
+            "${SONAR_HOST_URL}/api/user_tokens/generate" \
+            --data-urlencode "name=${TOKEN_NAME}" \
+            --data-urlencode "type=PROJECT_ANALYSIS_TOKEN" \
+            --data-urlencode "projectKey=${SONAR_PROJECT_KEY}" \
+            | jq -r '.token')
+
+          [[ -n "$SCAN_TOKEN" ]] || { echo "::error::Failed to generate scan token"; exit 1; }
+
+          echo "✅ Scan token generated for project '${SONAR_PROJECT_KEY}'"
+          echo "::add-mask::${SCAN_TOKEN}"
+          echo "SCAN_TOKEN=${SCAN_TOKEN}" >> "$GITHUB_ENV"
+
+      - name: Build and test
+        run: |
+          ./mvnw -B verify \
+            -Dtest='!PostgresIntegrationTests,!MySqlIntegrationTests'
+
+      - name: SonarQube analysis
+        run: |
+          ./mvnw -B org.sonarsource.scanner.maven:sonar-maven-plugin:4.0.0.4121:sonar \
+            -Dsonar.projectKey="${SONAR_PROJECT_KEY}" \
+            -Dsonar.host.url="${SONAR_HOST_URL}" \
+            -Dsonar.token="${SCAN_TOKEN}" \
+            -Dsonar.java.source=17 \
+            -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml
+
+      - name: Quality Gate check
+        id: quality-gate
+        run: |
+          echo "Waiting for SonarQube to process the analysis..."
+          for i in $(seq 1 24); do
+            RESPONSE=$(curl -sf -u "${SCAN_TOKEN}:" \
+              "${SONAR_HOST_URL}/api/qualitygates/project_status?projectKey=${SONAR_PROJECT_KEY}" || true)
+            STATUS=$(echo "$RESPONSE" | jq -r '.projectStatus.status' 2>/dev/null || echo "NONE")
+            if [[ "$STATUS" =~ ^(OK|ERROR|WARN)$ ]]; then break; fi
+            echo "  Status: ${STATUS:-pending} — retrying in 5s..."
+            sleep 5
+          done
+
+          echo ""
+          echo "══════════════════════════════════════════"
+          echo "  Quality Gate: $STATUS"
+          echo "══════════════════════════════════════════"
+
+          echo "$RESPONSE" | jq -r '
+            .projectStatus.conditions[] |
+            if .status == "ERROR" then "  ❌ \(.metricKey): \(.actualValue) (threshold: \(.errorThreshold), comparator: \(.comparator))"
+            elif .status == "WARN" then "  ⚠️  \(.metricKey): \(.actualValue) (threshold: \(.errorThreshold), comparator: \(.comparator))"
+            else "  ✅ \(.metricKey): \(.actualValue)"
+            end'
+
+          echo "══════════════════════════════════════════"
+
+          FAILED=$(echo "$RESPONSE" | jq '[.projectStatus.conditions[] | select(.status == "ERROR")] | length')
+          if [[ "$FAILED" -gt 0 ]]; then
+            echo "::error::Quality Gate FAILED — $FAILED metric(s) did not meet threshold"
+            exit 1
+          fi
+
+      - name: Notify Backstage on quality gate failure
+        if: always() && steps.quality-gate.outcome == 'failure'
+        run: |
+          echo "--- Backstage notification debug ---"
+          echo "BACKSTAGE_URL: ${BACKSTAGE_URL:-<not set>}"
+          echo "BACKSTAGE_CLEANUP_TOKEN set: $([[ -n "$BACKSTAGE_CLEANUP_TOKEN" ]] && echo yes || echo no)"
+          echo "SONAR_PROJECT_KEY: ${SONAR_PROJECT_KEY:-<not set>}"
+          echo "GITHUB_HEAD_REF: ${GITHUB_HEAD_REF:-<not set>}"
+
+          if [[ -z "$BACKSTAGE_URL" ]]; then
+            echo "::error::BACKSTAGE_URL is not set — cannot send notification"
+            exit 0
+          fi
+          if [[ -z "$BACKSTAGE_CLEANUP_TOKEN" ]]; then
+            echo "::error::BACKSTAGE_CLEANUP_TOKEN is not set — cannot send notification"
+            exit 0
+          fi
+
+          PAYLOAD="{
+            \"recipients\": { \"type\": \"entity\", \"entityRef\": \"group:default/platform-engineering\" },
+            \"payload\": {
+              \"title\": \"SonarQube Quality Gate Failed\",
+              \"description\": \"Quality gate failed for ${SONAR_PROJECT_KEY} on branch ${GITHUB_HEAD_REF}.\",
+              \"link\": \"${SONAR_HOST_URL}/dashboard?id=${SONAR_PROJECT_KEY}\",
+              \"severity\": \"high\",
+              \"topic\": \"sonarqube-quality-gate\"
+            }
+          }"
+
+          echo "Sending notification to: ${BACKSTAGE_URL}/api/notifications"
+
+          HTTP_CODE=$(curl -s -o /tmp/bs-notify-response.json -w "%{http_code}" \
+            -X POST "${BACKSTAGE_URL}/api/notifications" \
+            -H "Content-Type: application/json" \
+            -H "Authorization: Bearer ${BACKSTAGE_CLEANUP_TOKEN}" \
+            -d "${PAYLOAD}")
+
+          echo "HTTP response code: ${HTTP_CODE}"
+          echo "Response body:"
+          cat /tmp/bs-notify-response.json 2>/dev/null || echo "<empty response>"
+
+          if [[ "$HTTP_CODE" -ge 200 && "$HTTP_CODE" -lt 300 ]]; then
+            echo "✅ Backstage notification sent"
+          else
+            echo "⚠️  Backstage notification failed (HTTP ${HTTP_CODE})"
+          fi
+
+      - name: Revoke scan token
+        if: always()
+        run: |
+          curl -sf -X POST \
+            -u "${SONAR_ADMIN_TOKEN}:" \
+            "${SONAR_HOST_URL}/api/user_tokens/revoke" \
+            --data-urlencode "name=gitea-scan-${SONAR_PROJECT_KEY}" \
+            && echo "✅ Scan token revoked" \
+            || echo "⚠️  Token revocation failed"

.gitea/workflows/techdocs.yml

@@ -0,0 +1,108 @@
+name: Build and Publish TechDocs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "catalog-info.yaml"
+  workflow_dispatch: {}
+
+env:
+  TECHDOCS_AZURE_BLOB_CONTAINER_NAME: 
+  AZURE_FEDERATED_TOKEN_FILE: /var/run/secrets/azure/tokens/azure-identity-token
+  AZURE_ACCOUNT_NAME: "bstagecjotdevsttechdocs"
+  ENTITY_NAMESPACE: default
+  ENTITY_KIND: component
+  ENTITY_NAME: lint-enforcement-v3
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: read and set output
+        id: read_env
+        run: |
+          echo "$AZURE_FEDERATED_TOKEN_FILE"
+          env | grep AZURE
+          echo "$(cat $AZURE_FEDERATED_TOKEN_FILE)"
+
+      # act-based Gitea runners run as root — sudo is not available.
+      # apt-get is called directly; works whether root or not.
+      - name: Bootstrap pip
+        run: |
+          python3 --version
+          if python3 -m pip --version 2>/dev/null; then
+            echo "pip already available"
+          elif python3 -m ensurepip --version 2>/dev/null; then
+            python3 -m ensurepip --upgrade
+          else
+            apt-get update -qq
+            apt-get install -y python3-pip
+          fi
+          python3 -m pip install --upgrade pip
+          python3 -m pip --version
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install \
+            mkdocs-techdocs-core==1.* \
+            mkdocs-git-revision-date-localized-plugin \
+            mkdocs-awesome-pages-plugin
+
+          npm install -g @techdocs/cli
+          npm cache clean --force
+
+      # mkdocs has no dry-run flag — build into a temp dir to validate config
+      # and catch any broken links or missing pages early.
+      - name: Validate MkDocs config
+        run: mkdocs build --strict --site-dir /tmp/mkdocs-validate
+
+      - name: Build TechDocs site
+        run: |
+          techdocs-cli generate \
+            --source-dir . \
+            --output-dir ./site \
+            --no-docker \
+            --verbose
+
+      # act runners don't include az by default — install via Microsoft's
+      # official script which works on Debian/Ubuntu without sudo.
+      - name: Install Azure CLI
+        run: |
+          if command -v az &>/dev/null; then
+            echo "Azure CLI already installed: $(az version --query '"azure-cli"' -o tsv)"
+          else
+            curl -sL https://aka.ms/InstallAzureCLIDeb | bash
+          fi
+
+      - name: Azure login (OIDC)
+        run: |
+          az login \
+            --service-principal \
+            --username "$AZURE_CLIENT_ID" \
+            --tenant "$AZURE_TENANT_ID" \
+            --federated-token "$(cat $AZURE_FEDERATED_TOKEN_FILE)"
+
+          echo "✓ Azure login successful"
+
+      - name: Publish TechDocs site
+        run: |
+          echo "$AZURE_ACCOUNT_NAME"
+          echo "$ENTITY_NAMESPACE"
+          echo "$ENTITY_KIND"
+          echo "$ENTITY_NAME"
+          techdocs-cli publish \
+            --publisher-type azureBlobStorage \
+            --storage-name "techdocs" \
+            --azureAccountName "$AZURE_ACCOUNT_NAME" \
+            --entity "$ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME"