[patch] merge to master

Author: Hita-Pandya

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Build Documentation
+
+on:
+  push:
+    branches:
+      - '**'
+    tags-ignore:
+      - '**'
+  release:
+    types: [ published ]
+
+# Ensure only one build at a time for any branch, cancelling any in-progress builds
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py', '**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install package and doc build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build documentation
+        run: |
+          mkdocs build
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@4.1.7
+        if: ${{ github.event_name == 'release' || contains(github.event.head_commit.message, '[doc]') }}
+        with:
+          branch: gh-pages
+          folder: site
+
+# Made with Bob

.github/workflows/python-package.yml

@@ -26,10 +26,10 @@ jobs:
 
       # 2. Python Package Build
       # -------------------------------------------------------------------------------------------
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: 3.12
 
       - name: Build the Python package
         env:

.github/workflows/python-release.yml

@@ -25,10 +25,10 @@ jobs:
 
       # 2. Python Package Build
       # -------------------------------------------------------------------------------------------
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: 3.12
 
       - name: Build the Python package
         env:

.gitignore

@@ -19,3 +19,5 @@ venv/
 # Other
 kubectl.exe
 /build
+/.vscode
+/site

.pre-commit-config.yaml

@@ -13,4 +13,5 @@ repos:
     rev: 0.13.1+ibm.64.dss
     hooks:
       - id: detect-secrets
+        additional_dependencies: [boxsdk<4]
         args: [--baseline, .secrets.baseline, --use-all-plugins, --fail-on-unaudited]

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2025-10-27T10:20:07Z",
+  "generated_at": "2025-12-25T19:13:06Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -82,15 +82,53 @@
         "hashed_secret": "053f5ed451647be0bbb6f67b80d6726808cad97e",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 35,
+        "line_number": 44,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "4f75456d6c1887d41ed176f7ad3e2cfff3fdfd91",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 44,
+        "line_number": 53,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/cli/create-initial-users.md": [
+      {
+        "hashed_secret": "33f220dd67f717cc949db63e21c90e130a6137da",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 126,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/cli/index.md": [
+      {
+        "hashed_secret": "33f220dd67f717cc949db63e21c90e130a6137da",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 56,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/cli/notify-slack.md": [
+      {
+        "hashed_secret": "1572c8dd915cf3bdecae817b1cb65847b4e94037",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 61,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "2d8b1074eb78b85690ced3d2cc0aed0466f6f652",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 207,
         "type": "Secret Keyword",
         "verified_result": null
       }

AGENT_INSTRUCTIONS.md

@@ -0,0 +1,84 @@
+# python-devops AI Coding Instructions
+
+## Project Overview
+Python package for IBM Maximo DevOps utilities. Provides command-line tools for deployment automation, database validation, Slack notifications, and user management. Distributed as installable package with `setup.py`/`pyproject.toml` and standalone scripts in `bin/`.
+
+## Architecture
+- **bin/**: Executable CLI scripts (entry points)
+  - `mas-devops-*`: Command-line tools for specific operations
+  - Scripts import from `src/` package for implementation
+  - Each script typically wraps a single operational task
+- **src/**: Main package source code
+  - Organized by module/function (import path: `from mas_devops import ...`)
+  - Core utilities: configuration management, API clients, database handlers
+- **test/**: Test suite (pytest structure)
+  - Mirror `src/` structure in test files
+  - Run with `pytest` or `make test`
+- **build/**: Generated artifacts (don't edit)
+  - `*.egg-info/`: Package metadata
+  - `dist/`, `*.whl`: Distribution packages
+- **setup.py** / **pyproject.toml**: Package definition
+  - Entry points defined in setup.py pointing to `bin/` scripts
+  - Dependencies in both files (must keep in sync)
+  - Version defined once (check both files)
+
+## Key Patterns
+- **CLI Tool Pattern**: `bin/mas-devops-*` scripts are thin wrappers
+  - Import main logic from `src/mas_devops/`
+  - Handle argument parsing and error reporting
+  - Example: `mas-devops-notify-slack` → calls slack notification module
+- **Dependency Management**:
+  - Core dependencies in `setup.py` `install_requires`
+  - Dev dependencies in `setup.py` `extras_require['dev']`
+  - `requirements.txt` for pinned versions (reproducible installs)
+  - Keep all three in sync
+- **Entry Points**: `setup.py` defines CLI commands
+  - Format: `'mas-devops-task-name = mas_devops.module:main_function'`
+  - Creates executable scripts in `bin/` when package installed
+- **Module Organization**: Import directly from package
+  - `from mas_devops.db2_validator import validate_config`
+  - Avoid deep nesting; keep public API clear
+
+## Development Workflow
+```bash
+make install           # Install package in dev mode (pip install -e .)
+make test              # Run pytest suite
+make test-verbose      # Pytest with verbose output
+make build             # Build distribution (wheel/tarball)
+make clean             # Remove build artifacts
+make all               # Clean, test, build
+```
+
+## Important Conventions
+- **Python Version**: Check `setup.py` for `python_requires` (e.g., `>=3.8`)
+- **Entry Points**: Adding new CLI tool requires editing `setup.py` entry_points section
+- **Error Handling**: CLI scripts should catch exceptions and exit with meaningful error messages
+- **Logging**: Use Python logging module; configure in main module
+- **Testing**: Test structure mirrors source; test file for `src/module.py` is `test/test_module.py`
+- **Documentation**: Docstrings in functions should describe parameters, return, exceptions
+- **Imports**: Use absolute imports from package (`from mas_devops import ...`), not relative
+
+## Common CLI Tools (Reference)
+- `mas-devops-create-initial-users-for-saas`: User provisioning (SaaS)
+- `mas-devops-db2-validate-config`: Validate DB2 configuration
+- `mas-devops-notify-slack`: Send notifications
+- `mas-devops-saas-job-cleaner`: Cleanup SaaS jobs
+
+## Integration Points
+- **ansible-devops**: Playbooks call these Python utilities for infrastructure setup
+- **playbook**: Runbooks document procedures; Python tools automate them
+- **Standalone Usage**: Scripts can be called independently or from other tools via entry points
+- **Distribution**: Package installed via pip; entry points register CLI commands globally
+
+## When Adding New CLI Tool
+1. Create implementation module in `src/mas_devops/`
+2. Create script in `bin/mas-devops-tool-name` or update `setup.py` entry_points
+3. Add entry to `setup.py` entry_points section
+4. Add tests in `test/` matching module structure
+5. Update `requirements.txt` if adding dependencies
+6. Test with `make install` then run `mas-devops-tool-name --help`
+
+## Packaging & Distribution
+- Build: `python -m build` or `make build`
+- Outputs: wheel file in `dist/` ready for pip install
+- Version managed in `setup.py` (check both setup.py and pyproject.toml)

MANIFEST.in

@@ -1,3 +1,4 @@
 include src/mas/devops/templates/*.json.j2
 include src/mas/devops/templates/*.yml.j2
 include src/mas/devops/data/catalogs/*.yaml
+include src/mas/devops/data/*.yaml

Makefile

@@ -1,30 +1,30 @@
 .PHONY: install build lint pyinstaller clean
 
-venv:
-	python3 -m venv venv
+.venv:
+	python3 -m venv .venv
 
 clean:
-	rm -rf venv
+	rm -rf .venv
 
-install: venv
-	. venv/bin/activate && python -m pip install --editable .[dev]
+install: .venv
+	. .venv/bin/activate && python -m pip install --editable .[dev]
 
-build: venv
+build: .venv
 	rm -f README.rst
-	. venv/bin/activate && python -m build
+	. .venv/bin/activate && python -m build
 
 # Note: "make install" needs to be ran once before this target will work, but we
 # don't want to set it as a dependency otherwise it unnecessarily slows down
 # fast implement/test cycles.  "make install" created an editable install of the
 # package which is linked to the files you are editing so there is no need to
 # re-install after each change.
 unit-test:
-	. venv/bin/activate && pytest test/src/mock
+	. .venv/bin/activate && pytest test/src/mock
 
-lint: venv
+lint: .venv
 	rm -f README.rst
-	. venv/bin/activate && flake8 src --count --select=E9,F63,F7,F82 --show-source --statistics && flake8 src --count --exit-zero --max-complexity=10 --max-line-length=200 --statistics
+	. .venv/bin/activate && flake8 src --count --select=E9,F63,F7,F82 --show-source --statistics && flake8 src --count --exit-zero --max-complexity=10 --max-line-length=200 --statistics
 
 pyinstaller: venv
 	rm -f README.rst
-	. venv/bin/activate && pyinstaller src/mas-upgrade --onefile --noconfirm --add-data="src/mas/devops/templates/ibm-mas-tekton.yaml:mas/devops/templates" --add-data="src/mas/devops/templates/subscription.yml.j2:mas/devops/templates/" --add-data="src/mas/devops/templates/pipelinerun-upgrade.yml.j2:mas/devops/templates/"
+	. .venv/bin/activate && pyinstaller src/mas-upgrade --onefile --noconfirm --add-data="src/mas/devops/templates/ibm-mas-tekton.yaml:mas/devops/templates" --add-data="src/mas/devops/templates/subscription.yml.j2:mas/devops/templates/" --add-data="src/mas/devops/templates/pipelinerun-upgrade.yml.j2:mas/devops/templates/"

bin/mas-devops-create-initial-users-for-saas

@@ -10,21 +10,18 @@
 #
 # *****************************************************************************
 
+from mas.devops.users import MASUserUtils
+from botocore.exceptions import ClientError
+import boto3
+import sys
+import json
+import yaml
 from kubernetes import client, config
 from kubernetes.config.config_exception import ConfigException
 import argparse
 import logging
 import urllib3
 urllib3.disable_warnings()
-import yaml
-import json
-import sys
-
-import boto3
-from botocore.exceptions import ClientError
-
-from mas.devops.users import MASUserUtils
-
 
 
 if __name__ == "__main__":
@@ -38,7 +35,6 @@ if __name__ == "__main__":
     parser.add_argument("--admin-dashboard-port", required=False, default=443)
     parser.add_argument("--manage-api-port", required=False, default=443)
 
-
     group = parser.add_mutually_exclusive_group(required=True)
     group.add_argument("--initial-users-yaml-file")
     group.add_argument("--initial-users-secret-name")
@@ -66,7 +62,6 @@ if __name__ == "__main__":
     admin_dashboard_port = args.admin_dashboard_port
     manage_api_port = args.manage_api_port
 
-
     logger.info("Configuration:")
     logger.info("--------------")
     logger.info(f"mas_instance_id:           {mas_instance_id}")
@@ -88,7 +83,6 @@ if __name__ == "__main__":
         config.load_kube_config()
         logger.debug("Loaded kubeconfig file")
 
-
     user_utils = MASUserUtils(mas_instance_id, mas_workspace_id, client.api_client.ApiClient(), coreapi_port=coreapi_port, admin_dashboard_port=admin_dashboard_port, manage_api_port=manage_api_port)
 
     if initial_users_secret_name is not None:
@@ -100,7 +94,7 @@ if __name__ == "__main__":
             service_name='secretsmanager',
         )
         try:
-            initial_users_secret = aws_sm_client.get_secret_value( # pragma: allowlist secret
+            initial_users_secret = aws_sm_client.get_secret_value(  # pragma: allowlist secret
                 SecretId=initial_users_secret_name
             )
         except ClientError as e:
@@ -109,16 +103,15 @@ if __name__ == "__main__":
                 sys.exit(0)
 
             raise Exception(f"Failed to fetch secret {initial_users_secret_name}: {str(e)}")
-        
+
         secret_json = json.loads(initial_users_secret['SecretString'])
         initial_users = user_utils.parse_initial_users_from_aws_secret_json(secret_json)
     elif initial_users_yaml_file is not None:
         with open(initial_users_yaml_file, 'r') as file:
             initial_users = yaml.safe_load(file)
     else:
         raise Exception("Something unexpected happened")
-    
-    
+
     result = user_utils.create_initial_users_for_saas(initial_users)
 
     # if user details were sourced from an AWS SM secret, remove the completed entries from the secret
@@ -133,14 +126,13 @@ if __name__ == "__main__":
         if has_updates:
             logger.info(f"Updating secret {initial_users_secret_name}")
             try:
-                aws_sm_client.update_secret( # pragma: allowlist secret
+                aws_sm_client.update_secret(  # pragma: allowlist secret
                     SecretId=initial_users_secret_name,
                     SecretString=json.dumps(secret_json)
                 )
             except ClientError as e:
                 raise Exception(f"Failed to update secret {initial_users_secret_name}: {str(e)}")
-            
 
     if len(result["failed"]) > 0:
-        failed_user_ids = list(map(lambda u : u["email"], result["failed"]))
-        raise Exception(f"Sync failed for the following user IDs {failed_user_ids}")
+        failed_user_ids = list(map(lambda u: u["email"], result["failed"]))
+        raise Exception(f"Sync failed for the following user IDs {failed_user_ids}")