Skip to content

Commit 99ad958

Browse files
RossBugginsNHSRossBugginsNHS
committed
docs: Add monitoring and verification tools documentation
- Added Copilot Instruction #15: GitHub CLI for monitoring workflows - Commands: gh run list, gh run view, gh run watch - Setup: gh repo set-default, gh auth login - Added Copilot Instruction #16: SonarCloud public API for coverage - API endpoint, parameters, and examples - Response format and interpretation - Troubleshooting guidance for 0% coverage issues - Added 'Monitoring and Verification' section to TESTING_PLAN.md - GitHub Actions monitoring with gh CLI - SonarCloud coverage monitoring with API examples - Detailed response format documentation This provides automated tools for verifying CI/CD runs and coverage detection without requiring manual browser interaction.
1 parent 94a165f commit 99ad958

File tree

2 files changed

+164
-0
lines changed

2 files changed

+164
-0
lines changed

‎src/.github/copilot-instructions.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,23 @@
3636
- Always test that the prerequisites install correctly before running tests
3737
- Add a comment in unit.sh explaining what each section does
3838

39+
15. **Use GitHub CLI for monitoring CI/CD** - When monitoring GitHub Actions workflow runs:
40+
- Use `gh run list --branch <branch-name> --limit <n>` to list recent workflow runs
41+
- Use `gh run view <run-id>` to view details of a specific run
42+
- Use `gh run watch <run-id>` to watch a run in progress
43+
- If `gh` commands fail with "No default remote repository", run `gh repo set-default NHSDigital/nhs-notify-digital-letters`
44+
- If authentication is required, the user will handle `gh auth login`
45+
46+
16. **Use SonarCloud API for coverage monitoring** - To check coverage metrics on branches:
47+
- **Public API (no auth required)**: `https://sonarcloud.io/api/measures/component`
48+
- **Parameters**:
49+
- `component`: `NHSDigital_nhs-notify-digital-letters` (project) or `NHSDigital_nhs-notify-digital-letters:src/project-name` (specific component)
50+
- `branch`: URL-encoded branch name (e.g., `rossbugginsnhs/2025-11-04/eventcatalog-001`)
51+
- `metricKeys`: `coverage,new_coverage,lines_to_cover,new_lines_to_cover`
52+
- **Example**: `curl -s "https://sonarcloud.io/api/measures/component?component=NHSDigital_nhs-notify-digital-letters:src/asyncapigenerator&branch=rossbugginsnhs/2025-11-04/eventcatalog-001&metricKeys=coverage,new_coverage,lines_to_cover,new_lines_to_cover" | python3 -m json.tool`
53+
- Use this to verify coverage is being detected after SonarCloud configuration changes
54+
- Look for `new_coverage` in the response - should not be 0.0% if tests are working
55+
3956
## Quick Reference
4057

4158
- **TESTING_PLAN.md**: Main testing plan document with progress tracker and changelog

‎src/TESTING_PLAN.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,30 @@ This document outlines the comprehensive plan for implementing unit tests across
7070

7171
**Track all implementation activities here. Add new entries at the top (reverse chronological order).**
7272

73+
### 2025-11-04 13:26 GMT - Added Monitoring and Verification Documentation
74+
75+
- **Author**: GitHub Copilot
76+
- **Activity**: Documented GitHub CLI and SonarCloud API usage for monitoring CI/CD and coverage
77+
- **Changes**:
78+
- Added Copilot Instruction #15: GitHub CLI usage for monitoring workflow runs
79+
- Commands: `gh run list`, `gh run view`, `gh run watch`
80+
- Setup instructions for `gh repo set-default` and `gh auth login`
81+
- Added Copilot Instruction #16: SonarCloud public API for coverage monitoring
82+
- API endpoint and parameters documented
83+
- Example curl commands for project-wide and component-specific queries
84+
- Response format and interpretation guide
85+
- Troubleshooting tips for 0.0% coverage issues
86+
- Added new "Monitoring and Verification" section to TESTING_PLAN.md:
87+
- GitHub Actions monitoring with `gh` CLI commands
88+
- SonarCloud coverage monitoring with API examples
89+
- Response format documentation
90+
- Troubleshooting guidance
91+
- **Files Modified**:
92+
- `src/.github/copilot-instructions.md` - Added instructions #15 and #16
93+
- `src/TESTING_PLAN.md` - Added "Monitoring and Verification" section
94+
- **Rationale**: Enables automated monitoring of CI/CD runs and SonarCloud coverage without manual browser interaction. Provides tools for verifying that coverage reports are being detected correctly.
95+
- **Status**: Complete monitoring capabilities documented
96+
7397
### 2025-11-04 13:12 GMT - Added SonarCloud Integration for Python Coverage
7498

7599
- **Author**: GitHub Copilot
@@ -874,6 +898,129 @@ The GitHub Actions workflow (`.github/workflows/stage-2-test.yaml`):
874898

875899
Without these configurations, SonarCloud will show 0% coverage for Python projects.
876900

901+
## Monitoring and Verification
902+
903+
### GitHub Actions Monitoring
904+
905+
Use the **GitHub CLI** (`gh`) to monitor workflow runs:
906+
907+
#### List Recent Workflow Runs
908+
909+
```bash
910+
gh run list --branch <branch-name> --limit 5
911+
```
912+
913+
Example:
914+
915+
```bash
916+
gh run list --branch rossbugginsnhs/2025-11-04/eventcatalog-001 --limit 5
917+
```
918+
919+
#### View Workflow Run Details
920+
921+
```bash
922+
gh run view <run-id>
923+
```
924+
925+
#### Watch a Running Workflow
926+
927+
```bash
928+
gh run watch <run-id>
929+
```
930+
931+
#### Setup (if needed)
932+
933+
If you encounter "No default remote repository" error:
934+
935+
```bash
936+
gh repo set-default NHSDigital/nhs-notify-digital-letters
937+
```
938+
939+
If authentication is required, run:
940+
941+
```bash
942+
gh auth login
943+
```
944+
945+
### SonarCloud Coverage Monitoring
946+
947+
Use the **SonarCloud public API** to check coverage metrics (no authentication required for public repos):
948+
949+
#### API Endpoint
950+
951+
```bash
952+
https://sonarcloud.io/api/measures/component
953+
```
954+
955+
#### Parameters
956+
957+
- `component`: Project or component key
958+
- Project: `NHSDigital_nhs-notify-digital-letters`
959+
- Component: `NHSDigital_nhs-notify-digital-letters:src/project-name`
960+
- `branch`: URL-encoded branch name (e.g., `rossbugginsnhs/2025-11-04/eventcatalog-001`)
961+
- `metricKeys`: Comma-separated metrics (e.g., `coverage,new_coverage,lines_to_cover,new_lines_to_cover`)
962+
963+
#### Example: Check Project-Wide Coverage
964+
965+
```bash
966+
curl -s "https://sonarcloud.io/api/measures/component?component=NHSDigital_nhs-notify-digital-letters&branch=rossbugginsnhs/2025-11-04/eventcatalog-001&metricKeys=coverage,new_coverage,lines_to_cover,new_lines_to_cover" | python3 -m json.tool
967+
```
968+
969+
#### Example: Check Specific Component Coverage
970+
971+
```bash
972+
curl -s "https://sonarcloud.io/api/measures/component?component=NHSDigital_nhs-notify-digital-letters:src/asyncapigenerator&branch=rossbugginsnhs/2025-11-04/eventcatalog-001&metricKeys=coverage,new_coverage,lines_to_cover,new_lines_to_cover" | python3 -m json.tool
973+
```
974+
975+
#### Response Format
976+
977+
```json
978+
{
979+
"component": {
980+
"key": "NHSDigital_nhs-notify-digital-letters:src/asyncapigenerator",
981+
"measures": [
982+
{
983+
"metric": "coverage",
984+
"value": "94.0"
985+
},
986+
{
987+
"metric": "new_coverage",
988+
"periods": [
989+
{
990+
"index": 1,
991+
"value": "94.0"
992+
}
993+
]
994+
},
995+
{
996+
"metric": "lines_to_cover",
997+
"value": "246"
998+
},
999+
{
1000+
"metric": "new_lines_to_cover",
1001+
"periods": [
1002+
{
1003+
"index": 1,
1004+
"value": "246"
1005+
}
1006+
]
1007+
}
1008+
]
1009+
}
1010+
}
1011+
```
1012+
1013+
#### Interpreting Results
1014+
1015+
- `coverage`: Overall coverage percentage
1016+
- `new_coverage`: Coverage for new/changed code on the branch
1017+
- `lines_to_cover`: Total lines that should be covered
1018+
- `new_lines_to_cover`: New lines that should be covered
1019+
- **If `new_coverage` is 0.0%**: SonarCloud is not detecting your Python coverage reports
1020+
- Check that `coverage.xml` is being generated
1021+
- Verify `sonar-scanner.properties` has correct paths
1022+
- Confirm `scripts/tests/unit.sh` runs `make coverage` (not `make test`)
1023+
8771024
### Testing CI/CD Changes Locally
8781025

8791026
Before committing changes to `scripts/tests/unit.sh`, test locally:

0 commit comments

Comments
 (0)