Skip to content

Commit 45dfa69

Browse files
Copilotfermga
Copilot
and
fermga
committed
Update documentation to reflect workflow changes
Co-authored-by: fermga <203334638+fermga@users.noreply.github.com>
1 parent 648be95 commit 45dfa69

File tree

3 files changed

+161
-8
lines changed

3 files changed

+161
-8
lines changed

‎.github/WORKFLOWS.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# GitHub Actions Workflows
2+
3+
This document describes the CI/CD workflows configured for this repository.
4+
5+
## Active Workflows
6+
7+
### Core Development Workflows
8+
9+
#### 1. CI (`ci.yml`)
10+
**Triggers:** Push and PR to main/master branches
11+
**Purpose:** Core continuous integration testing and quality checks
12+
**Jobs:**
13+
- **Format check**: Runs pre-commit hooks (black, isort, pydocstyle)
14+
- **Type check and static analysis**: Runs flake8, mypy, pyright, vulture, and language policy enforcement
15+
- **Changelog fragments**: Enforces changelog fragments for PRs
16+
- **Tests**: Runs pytest across Python 3.9-3.13 with coverage reporting
17+
18+
**Status:** ✅ Working (has legitimate doctest failures in codebase, not workflow issues)
19+
20+
#### 2. Docs (`docs.yml`)
21+
**Triggers:** Push and PR to main branch
22+
**Purpose:** Build and validate documentation
23+
**Jobs:**
24+
- Build MkDocs site with strict mode
25+
- Run Sphinx doctests
26+
- Perform link checking
27+
28+
**Status:** ✅ Working (has legitimate doctest failures in codebase, not workflow issues)
29+
30+
### Security Workflows
31+
32+
#### 3. CodeQL Analysis (`codeql-analysis.yml`)
33+
**Triggers:** Push/PR to main/master, weekly schedule (Monday 3 AM UTC)
34+
**Purpose:** Advanced security scanning using GitHub CodeQL
35+
**Jobs:**
36+
- Initialize CodeQL for Python
37+
- Autobuild and analyze
38+
- Upload SARIF results to GitHub Security tab
39+
40+
**Status:** ✅ Working correctly
41+
42+
#### 4. SAST Lint (`sast-lint.yml`)
43+
**Triggers:** Push to main, PRs, manual dispatch
44+
**Purpose:** Static Application Security Testing
45+
**Jobs:**
46+
- **Bandit scan**: Security vulnerability detection in Python code
47+
- **Semgrep scan**: Pattern-based security and bug detection
48+
49+
**Status:** ✅ Working correctly
50+
51+
#### 5. Dependency Vulnerability Audit (`pip-audit.yml`)
52+
**Triggers:** Push/PR to main/master, weekly schedule (Monday 5 AM UTC)
53+
**Purpose:** Scan Python dependencies for known vulnerabilities
54+
**Jobs:**
55+
- Install all project dependencies
56+
- Run pip-audit against installed packages
57+
- Upload JSON report artifact
58+
- Fail build if vulnerabilities detected
59+
60+
**Status:** ✅ Working correctly
61+
62+
### Quality Assurance Workflows
63+
64+
#### 6. Reproducibility Check (`reproducibility.yml`)
65+
**Triggers:** Push/PR to main/master, manual dispatch
66+
**Purpose:** Verify benchmark reproducibility (TNFR canonical requirement)
67+
**Jobs:**
68+
- Run benchmarks twice with same seed
69+
- Compare manifest checksums
70+
- Verify identical results
71+
72+
**Status:** ✅ Working correctly
73+
74+
#### 7. Performance Regression (`performance-regression.yml`)
75+
**Triggers:** PRs to main/master, manual dispatch
76+
**Purpose:** Detect performance degradations
77+
**Jobs:**
78+
- Run performance regression test suite
79+
- Mark slow tests appropriately
80+
81+
**Status:** ✅ Working correctly
82+
83+
#### 8. Verify Internal References (`verify-references.yml`)
84+
**Triggers:** Push/PR affecting markdown/notebook files
85+
**Purpose:** Validate internal documentation links
86+
**Jobs:**
87+
- Scan 985+ internal references
88+
- Report broken links
89+
90+
**Status:** ⚠️ Working but reports 75 broken links (codebase issue, not workflow)
91+
92+
### Infrastructure Workflows
93+
94+
#### 9. Lint Workflows (`lint-workflows.yml`)
95+
**Triggers:** Push/PR affecting workflows, tools, or scripts
96+
**Purpose:** Validate workflow configurations
97+
**Jobs:**
98+
- Check for invalid Bandit format usage (SARIF not supported)
99+
- Verify bandit_to_sarif.py converter exists
100+
101+
**Status:** ✅ Working correctly
102+
103+
#### 10. Release (`release.yml`)
104+
**Triggers:** Push to main, manual dispatch
105+
**Purpose:** Automated semantic release process
106+
**Jobs:**
107+
- **Prepare**: Detect next version, compile changelog, apply tags
108+
- **Publish**: Build distributions, sign with GPG, publish to PyPI, create GitHub release
109+
110+
**Status:** ✅ Working correctly (intentionally skips when no release needed)
111+
112+
## Removed Workflows
113+
114+
The following workflows were removed during cleanup:
115+
116+
### 1. `bandit.yml` (Removed)
117+
**Reason:** Duplicate functionality - Bandit already runs in `sast-lint.yml`
118+
119+
### 2. `black-duck-security-scan-ci.yml` (Removed)
120+
**Reason:** Requires paid Black Duck service with configuration not available in repository
121+
122+
### 3. `security-dashboard.yml` (Removed)
123+
**Reason:** Optional aggregator workflow with configuration issues; individual security scans (CodeQL, SAST, pip-audit) already provide comprehensive coverage
124+
125+
## Workflow Best Practices
126+
127+
1. **Concurrency Control**: All workflows use `concurrency` groups with `cancel-in-progress: true` to save CI resources
128+
2. **Caching**: Python dependencies and pip are cached to speed up builds
129+
3. **Matrix Testing**: CI tests across Python 3.9-3.13 to ensure compatibility
130+
4. **SARIF Integration**: Security workflows upload results to GitHub Security tab
131+
5. **Artifact Preservation**: Important outputs (reports, logs) are uploaded as artifacts
132+
133+
## Known Issues
134+
135+
These issues exist in the codebase, not in workflow configurations:
136+
137+
1. **Doctest Failures**:
138+
- Files: `docs/source/api/api_mapping.rst`, `docs/source/how_to_reproduce_results.rst`
139+
- Cause: Unexpected warnings and validation errors
140+
- Impact: CI and Docs workflows report failures
141+
142+
2. **Broken Documentation Links**:
143+
- 75 broken internal references
144+
- Common patterns: missing API pages, moved/renamed files
145+
- Impact: Verify Internal References workflow reports failures
146+
147+
## Maintenance Notes
148+
149+
- All workflows follow TNFR canonical requirements (reproducibility, traceability, English-only)
150+
- Security workflows run on schedule to catch newly disclosed vulnerabilities
151+
- Release workflow requires semantic commit messages for version bumping
152+
- No workflow credentials are committed to the repository (use GitHub Secrets)

‎docs/source/security/monitoring.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,19 @@ The TNFR engine security discipline aggregates automated signals to catch regres
1111
| `pip-audit` | `.github/workflows/pip-audit.yml` | JSON (`pip-audit.json`) | Evaluates vulnerabilities in installed packages and their impact on νf and the execution phase. |
1212
| Bandit + Semgrep | `.github/workflows/sast-lint.yml` | SARIF (`bandit.sarif`, `semgrep.sarif`) | Identifies risk patterns and records containment decisions within TNFR operators. |
1313

14-
The `security-dashboard.yml` workflow (see below) automatically downloads the available artifacts and consolidates the results in `docs/security/reports/` to streamline periodic reviews.
14+
Individual security workflows automatically upload their results to GitHub Security tab and as workflow artifacts for review.
1515

1616
## Review cadence
1717

18-
- **Weekly (Mondays)**: inspect the report generated by `security-dashboard.yml`, validate dashboard trends, and log corrective actions. This review aligns with the existing CodeQL (`03:00 UTC`) and `pip-audit` (`05:00 UTC`) cron schedules.
18+
- **Weekly (Mondays)**: Review security scan results from GitHub Security tab and workflow artifacts. This review aligns with the existing CodeQL (`03:00 UTC`) and `pip-audit` (`05:00 UTC`) cron schedules.
1919
- **After every critical alert**: trigger a controlled dissonance session on the affected component, document the resolution, and update the `C(t)` and `Si` metrics when applicable.
2020
- **Monthly**: audit the Dependabot configuration, SAST rule coverage, and the dashboard scope to uphold operator closure and fidelity to TNFR semantics.
2121

22-
## What to expect in the reports repository
22+
## What to expect in workflow artifacts
2323

24-
1. A Markdown summary with per-tool counts (critical/high/medium/low) and links to the originating Actions runs.
25-
2. References to the SARIF/JSON artifacts downloaded during execution.
26-
3. A minimal trace of when the report was generated (UTC `timestamp`) to maintain structural traceability.
24+
1. **CodeQL**: SARIF files in the `codeql-python-results` artifact with detailed security analysis
25+
2. **Bandit + Semgrep**: SARIF files (`bandit-sarif`, `semgrep-sarif`) uploaded to GitHub Security tab
26+
3. **pip-audit**: JSON report artifact (`pip-audit-report`) with dependency vulnerability details
27+
4. All results are accessible via GitHub Security tab and workflow run artifacts
2728

28-
The `docs/security/reports/` directory is reserved for pipeline-generated artifacts; files are stored as GitHub Actions artifacts and distributed through automated notifications (Slack or other configured webhooks).
29+
Security findings are automatically integrated into GitHub's native security alerts for centralized monitoring.

‎docs/source/security/reports/.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
# Automatically generated by the security-dashboard workflow
1+
# Security reports directory (reserved for future use)
22
*
33
!.gitignore

0 commit comments

Comments
 (0)