Add Policy Integration Test pipeline and workflow setup instructions

docs/ado-pipelines/setup-guide.md

@@ -107,6 +107,52 @@ Once the pipeline is created, configure the branch protection policy for the `ma
 
 >:memo: NOTE: You can customize the linters and rulesets used by GitHub Super-Linter by modifying the configuration file of each linter in the `.github/linters` folder. For details on how to customize the GitHub Super-Linter, please refer to the [official project site](https://github.com/super-linter/super-linter).
 
+### Policy Integration Tests Pipeline
+
+When triggered from a PR, this pipeline use `git diff` to retrieve the list of changes in the PR, analyze the changes to identify required test cases from policy integration test, and then run the identified test cases to validate the functionality and effectiveness of the policies being changed in the PR.
+
+| Pipeline Name | Description | YAML File |
+| :------------ | :---------- | :-------- |
+| Validate-Policy-Integration-Tests | Policy Integration Tests | [`azure-pipelines-pr-policy-int-tests.yml`](../../.azuredevops/pipelines/validation/azure-pipelines-pr-policy-int-tests.yml) |
+
+Once the pipeline is created, configure the branch protection policy for the `main` branch to include this pipeline as a required check before merging.
+
+- `Build pipeline`: [`azure-pipelines-pr-policy-int-tests.yml`](../../.azuredevops/pipelines/validation/azure-pipelines-pr-policy-int-tests.yml)
+- Path filter: leave it blank
+- trigger: `Automatic`
+- Policy requirement: `Required`
+- `Build expiration`: `Immediately when main is updated`
+- Display name: `Policy Integration Tests`
+
+>:memo: NOTE: There is no need to specify the path filter for this pipeline because the pipeline has built-in logic to analyze and determine which test cases are required. If no test cases are identified based on the changes in the PR, the pipeline will be automatically skipped.
+
+Next, create an AES encryption key and store it in a variable group in the Azure DevOps project. This AES encryption key will be used to encrypt the Terraform state file generated by the test cases if any test cases are configured to deploy resources using Terraform.
+
+To create an AES encryption key, you can use the [newAesKey.ps1](../../scripts/support/policy-integration-test/newAesKey.ps1) PowerShell script provided in the `scripts` folder of this repository. This script will generate random AES key that can be used for AES encryption.:
+
+```PowerShell
+.\newAesKey.ps1
+```
+
+It will output a random AES key and its IV:
+
+```text
+Key                                          IV                       KeySize Created
+---                                          --                       ------- -------
+xvO6cbYyQao8ZbD+mtLSYmb0gzN+kYllxF83nOSDNgk= zoGQQ+iRPZ5+LnJ/uU/egA==     256 2026-04-05T23:45:28.8350380Z
+```
+
+Create a variable group called `**policy-testing**` in your Azure DevOps project and add the generated AES key and IV as secret variables in the variable group:
+
+- **aesEncryptionKey**: the value of the generated AES key (i.e. `xvO6cbYyQao8ZbD+mtLSYmb0gzN+kYllxF83nOSDNgk=`)
+- **aesIV**: the value of the generated AES IV (i.e. `zoGQQ+iRPZ5+LnJ/uU/egA==`)
+
+![variable-group](../images/pol-int-test-ado-variable-group.jpg)
+
+Make sure the Policy Inetegration Tests pipeline has access to this variable group.
+
+Lastly, it's best that you store the AES encryption key and IV in another secure location in case you need to examine the encrypted Terraform state files for troubleshooting or debugging purposes in the future.
+
 ## Step 7: Grant Policy Pipelines Permissions to Access Service Connections
 
 After creating the pipelines and service connections, you need to grant the pipelines permission to access the service connections in order for them to deploy resources to your Azure environment.

docs/github-action/setup-guide.md

@@ -128,6 +128,36 @@ This workflow performs a code scan using GitHub Super-Linter to validate all the
 
 >:memo: NOTE: You can customize the linters and rulesets used by GitHub Super-Linter by modifying the configuration file of each linter in the `.github/linters` folder. For details on how to customize the GitHub Super-Linter, please refer to the [official project site](https://github.com/super-linter/super-linter).
 
+
+### Policy Integration Tests
+
+When triggered from a PR, this workflow use `git diff` to retrieve the list of changes in the PR, analyze the changes to identify required test cases from policy integration test, and then run the identified test cases to validate the functionality and effectiveness of the policies being changed in the PR.
+
+Next, create an AES encryption key and store it as repository secret in the GitHub repository. This AES encryption key will be used to encrypt the Terraform state file generated by the test cases if any test cases are configured to deploy resources using Terraform.
+
+To create an AES encryption key, you can use the [newAesKey.ps1](../../scripts/support/policy-integration-test/newAesKey.ps1) PowerShell script provided in the `scripts` folder of this repository. This script will generate random AES key that can be used for AES encryption.:
+
+```PowerShell
+.\newAesKey.ps1
+```
+
+It will output a random AES key and its IV:
+
+```text
+Key                                          IV                       KeySize Created
+---                                          --                       ------- -------
+xvO6cbYyQao8ZbD+mtLSYmb0gzN+kYllxF83nOSDNgk= zoGQQ+iRPZ5+LnJ/uU/egA==     256 2026-04-05T23:45:28.8350380Z
+```
+
+Create the following secrets in your GitHub repository to store the AES key and IV values:
+
+- **AES_ENCRYPTION_KEY**: the value of the generated AES key (i.e. `xvO6cbYyQao8ZbD+mtLSYmb0gzN+kYllxF83nOSDNgk=`)
+- **AES_IV**: the value of the generated AES IV (i.e. `zoGQQ+iRPZ5+LnJ/uU/egA==`)
+
+![GitHub Secrets Configuration](../images/pol-int-test-gh-secrets.jpg)
+
+Lastly, it's best that you store the AES encryption key and IV in another secure location in case you need to examine the encrypted Terraform state files for troubleshooting or debugging purposes in the future.
+
 ## Step 7: Merge changes to the main branch and test run the workflows
 
 Create a PR to merge your changes into the `main` branch.