old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions

2026-01-15 18:37:59 +02:00
parent c631bacee2
commit 88a85cdd92
208 changed files with 32271 additions and 2287 deletions
--- a/docs/flows/10-cicd-gate-flow.md
+++ b/docs/flows/10-cicd-gate-flow.md
@@ -448,6 +448,119 @@ If `--attestation` is specified, CLI stores attestation:
 stellaops attestation show --scan $SCAN_ID

 # Verify attestation
+```
+
+### 8. PR/MR Comment and Status Integration
+
+StellaOps can post scan results as PR/MR comments and status checks for visibility directly in the SCM platform.
+
+#### GitHub PR Integration
+
+When scanning PRs, the system can:
+- Post a summary comment with findings count and severity breakdown
+- Create check runs with inline annotations
+- Update commit status with pass/fail verdict
+
+```yaml
+# GitHub Actions with PR comments
+- name: Scan with PR feedback
+  run: |
+    stellaops scan myapp:${{ github.sha }} \
+      --policy production \
+      --pr-comment \
+      --check-run \
+      --github-token ${{ secrets.GITHUB_TOKEN }}
+```
+
+Example PR comment format:
+
+```markdown
+## StellaOps Scan Results
+
+**Verdict:** :warning: WARN
+
+| Severity | Count |
+|----------|-------|
+| Critical | 0 |
+| High | 2 |
+| Medium | 5 |
+| Low | 12 |
+
+### Findings Requiring Attention
+
+| CVE | Severity | Package | Status |
+|-----|----------|---------|--------|
+| CVE-2026-1234 | High | lodash@4.17.21 | Fix available: 4.17.22 |
+| CVE-2026-5678 | High | express@4.18.0 | VEX: Not affected |
+
+<details>
+<summary>View full report</summary>
+
+[Download SARIF](https://stellaops.example.com/scans/abc123/sarif)
+[View in Console](https://stellaops.example.com/scans/abc123)
+
+</details>
+
+---
+*Scan ID: abc123 | Policy: production | [Evidence](https://stellaops.example.com/evidence/abc123)*
+```
+
+#### GitLab MR Integration
+
+For GitLab Merge Requests:
+- Post MR notes with findings summary
+- Update commit status on the pipeline
+- Create discussion threads for critical findings
+
+```yaml
+# GitLab CI with MR feedback
+scan:
+  stage: test
+  script:
+    - stellaops scan $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA \
+        --policy production \
+        --mr-comment \
+        --commit-status \
+        --gitlab-token $CI_JOB_TOKEN
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+```
+
+#### Comment Behavior Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--pr-comment` / `--mr-comment` | Post summary comment | false |
+| `--check-run` | Create GitHub check run with annotations | false |
+| `--commit-status` | Update commit status | false |
+| `--update-existing` | Edit previous comment instead of new | true |
+| `--collapse-details` | Use collapsible sections for long output | true |
+| `--evidence-link` | Include link to evidence bundle | true |
+
+#### Evidence Anchoring in Comments
+
+Comments include evidence references for auditability:
+
+- **Scan ID**: Unique identifier for the scan
+- **Policy Version**: The policy version used for evaluation
+- **Attestation Digest**: DSSE envelope digest for signed results
+- **Rekor Entry**: Log index when transparency logging is enabled
+
+#### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| No SCM token | Skip comment, log warning |
+| API rate limit | Retry with backoff, then skip |
+| Comment too long | Truncate with link to full report |
+| PR already merged | Skip comment |
+
+#### Offline Mode
+
+In air-gapped environments:
+- Comments are queued locally
+- Export comment payload for manual posting
+- Generate markdown file for offline review
 stellaops attestation verify --image myapp:v1.2.3 --policy production
 ```