PI-6 NGWPC-5541 Delivery

.github/ISSUE_TEMPLATE/capability.md

@@ -0,0 +1,38 @@
+---
+name: JIRA Story/Capability
+about: The structure for outlining work being done on a JIRA story
+labels: JIRA Story
+---
+
+# Capability
+
+<!-- Please link below the JIRA Story for coupling this issue to the scheduled work -->
+
+## Task
+
+<!-- Provide a clear and concise description of the task / work to be done to the repo
+
+* This ticket is meant to do XYZ and to accomplish the following:
+- ...
+- ...
+ -->
+
+## Plan/Outline
+
+<!-- Provide a few sentences about how this issue / story will be completed
+
+* This work will be done by creating a BMI module in the XYZ dir
+ -->
+
+
+### TODOS
+
+<!-- Create a checklist of what needs to be accomplished in this work -->
+- [ ]
+
+### Additional components / Context
+
+<!-- Add any other context or screenshots about the story here. You can also include links to examples of other programs that have something similar to your request. For example:
+
+* Another project [...] solved this by [...]
+-->

.github/workflows/cicd.yml

@@ -0,0 +1,217 @@
+name: CI/CD Pipeline
+
+on:
+    pull_request:
+        branches: [main, development]
+    push:
+        #TODO: remove dev branch
+        branches: [main, development]
+        # Consider how you want to handle version tags
+        tags: ['v*.*.*']
+
+permissions:
+    contents: read
+    packages: write
+    security-events: write
+
+env:
+    REGISTRY: ghcr.io
+    PYTHON_VERSION: '3.13'
+
+jobs:
+    setup:
+        runs-on: ubuntu-latest
+        outputs:
+            image_base: ${{ steps.vars.outputs.image_base }}
+            pr_tag: ${{ steps.vars.outputs.pr_tag }}
+            commit_sha: ${{ steps.vars.outputs.commit_sha }}
+            commit_sha_short: ${{ steps.vars.outputs.commit_sha_short }}
+            test_image_tag: ${{ steps.vars.outputs.test_image_tag }}
+        steps:
+            - name: Compute image vars
+              id: vars
+              shell: bash
+              run: |
+                set -euo pipefail
+                ORG="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
+                REPO="$(basename "${GITHUB_REPOSITORY}")"
+                IMAGE_BASE="${REGISTRY}/${ORG}/${REPO}"
+                echo "image_base=${IMAGE_BASE}" >> "$GITHUB_OUTPUT"
+
+                if [ "${GITHUB_EVENT_NAME}" = "pull_request" ]; then
+                    PR_NUM="${{ github.event.pull_request.number }}"
+                    PR_TAG="pr-${PR_NUM}-build"
+                    echo "pr_tag=${PR_TAG}" >> "$GITHUB_OUTPUT"
+                    echo "test_image_tag=${PR_TAG}" >> "$GITHUB_OUTPUT"
+                fi
+
+                if [ "${GITHUB_EVENT_NAME}" = "push" ]; then
+                    COMMIT_SHA="${GITHUB_SHA}"
+                    SHORT_SHA="${COMMIT_SHA:0:12}"
+                    echo "commit_sha=${COMMIT_SHA}" >> "$GITHUB_OUTPUT"
+                    echo "commit_sha_short=${SHORT_SHA}" >> "$GITHUB_OUTPUT"
+                    echo "test_image_tag=${SHORT_SHA}" >> "$GITHUB_OUTPUT"
+                fi
+
+    # TODO: Re-enable this job after linting rules are fixed or the code passes.
+    # ruff-linting:
+    #     name: Ruff Linting
+    #     runs-on: ubuntu-latest
+    #     steps:
+    #       - name: Checkout code
+    #         uses: actions/checkout@v4
+    #
+    #       - name: Install uv
+    #         uses: astral-sh/setup-uv@v5
+    #         with:
+    #             enable-cache: true
+    #             cache-dependency-glob: uv.lock pyproject.toml
+    #
+    #       - name: Set up Python
+    #         uses: astral-sh/setup-uv@v5
+    #         with:
+    #             python-version: "3.13"
+    #             cache-dependency-glob: uv.lock pyproject.toml
+    #
+    #       - name: Install dependencies
+    #         run: uv sync
+    #
+    #       - name: Run ruff check
+    #         run: |
+    #           uv run ruff check . --config pyproject.toml --output-format=github
+    #
+    #       - name: Run ruff formating check
+    #         run: |
+    #           uv run ruff format . --config pyproject.toml --check
+
+    # TODO: Re-enable this job after mocking AWS services, or the more integration focused tests are removed.
+    # The current unit tests require live AWS credentials, which is not practical for a standard CI environment.
+    # unit-test:
+    #     runs-on: ubuntu-latest
+    #     strategy:
+    #         matrix:
+    #             python-version: ['3.11', '3.12', '3.13']
+    #     steps:
+    #       - name: Checkout code
+    #         uses: actions/checkout@v4
+    #
+    #       - name: Install uv
+    #         uses: astral-sh/setup-uv@v5
+    #         with:
+    #             enable-cache: true
+    #             python-version: ${{ matrix.python-version }}
+    #             cache-dependency-glob: uv.lock pyproject.toml
+    #
+    #       - name: Install dependencies
+    #         run: uv sync
+    #
+    #       - name: Run tests
+    #         run: |
+    #           uv run pytest
+
+
+    build-and-scan:
+        name: Build and Scan Container
+        runs-on: ubuntu-latest
+        needs: setup
+        steps:
+          - uses: actions/checkout@v4
+          - name: Build image for scanning
+            id: build
+            uses: docker/build-push-action@v6
+            with:
+              context: .
+              file: ./docker/Dockerfile
+              # Load the image to the local Docker daemon, but do not push it
+              load: true
+              tags: ${{ needs.setup.outputs.image_base }}:${{ needs.setup.outputs.test_image_tag }}
+          - name: Scan container with Trivy
+            uses: aquasecurity/trivy-action@0.20.0
+            with:
+              # Scan the locally available image
+              image-ref: ${{ needs.setup.outputs.image_base }}:${{ needs.setup.outputs.test_image_tag }}
+              format: 'template'
+              template: '@/contrib/sarif.tpl'
+              output: 'trivy-results.sarif'
+              severity: 'CRITICAL,HIGH'
+          - name: Upload Trivy SARIF
+            uses: github/codeql-action/upload-sarif@v3
+            with:
+              sarif_file: 'trivy-results.sarif'
+
+    codeql-scan:
+        name: CodeQL Scan
+        if: github.event_name == 'pull_request' || github.event_name == 'push'
+        runs-on: ubuntu-latest
+        # The 'unit-test' job is disabled for now. When you re-enable it, uncomment the line below.
+        # needs: unit-test
+        permissions:
+            actions: read
+            contents: read
+            security-events: write
+        steps:
+          - uses: actions/checkout@v4
+          - name: Set up Python
+            uses: actions/setup-python@v5
+            with:
+              python-version: ${{ env.PYTHON_VERSION }}
+          - name: Install uv
+            uses: astral-sh/setup-uv@v5
+            with:
+              enable-cache: true
+              python-version: ${{ env.PYTHON_VERSION }}
+              cache-dependency-glob: uv.lock pyproject.toml
+          - name: Initialize CodeQL
+            uses: github/codeql-action/init@v3
+            with:
+              languages: python
+          - name: Install dependencies
+            run: uv sync
+          - name: Perform CodeQL Analysis
+            uses: github/codeql-action/analyze@v3
+
+    publish:
+        name: Publish to Registry
+        if: >
+          github.event_name == 'push' && (
+            github.ref == 'refs/heads/main' ||
+            github.ref == 'refs/heads/development' ||
+            startsWith(github.ref, 'refs/tags/v')
+          )
+        runs-on: ubuntu-latest
+        # When you re-enable your other jobs: ruff-linting, unit-test. Add them to this list.
+        needs: [setup, build-and-scan, codeql-scan]
+        steps:
+          - uses: actions/checkout@v4
+          - name: Prepare image tags
+            id: prep_tags
+            run: |
+              # Always start with the unique commit SHA tag for traceability
+              TAGS="${{ needs.setup.outputs.image_base }}:${{ needs.setup.outputs.commit_sha_short }}"
+
+              # If it's a push to the main branch, also add the 'latest' tag
+              if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
+                TAGS="$TAGS,${{ needs.setup.outputs.image_base }}:latest"
+              fi
+
+              # If the trigger was a version tag, add that version as a tag
+              if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
+                # github.ref_name holds the tag name (e.g., "v1.0.0")
+                VERSION_TAG=${{ github.ref_name }}
+                TAGS="$TAGS,${{ needs.setup.outputs.image_base }}:${VERSION_TAG}"
+              fi
+
+              echo "tags=${TAGS}" >> "$GITHUB_OUTPUT"
+          - name: Log in to registry
+            uses: docker/login-action@v3
+            with:
+              registry: ${{ env.REGISTRY }}
+              username: ${{ github.actor }}
+              password: ${{ secrets.GITHUB_TOKEN }}
+          - name: Build & push final image
+            uses: docker/build-push-action@v6
+            with:
+              context: .
+              file: ./docker/Dockerfile
+              push: true
+              tags: ${{ steps.prep_tags.outputs.tags }}