chore: clean .gitignore cache
This commit is contained in:
GitHub Actions
304
docs/implementation/SUPPLY_CHAIN_PR_COMMENTS_UPDATE.md
Normal file
304
docs/implementation/SUPPLY_CHAIN_PR_COMMENTS_UPDATE.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# Supply Chain Security PR Comments Update
|
||||
|
||||
## Overview
|
||||
|
||||
Modified the supply chain security workflow to update or create PR comments that always reflect the current security state, replacing stale scan results with fresh data.
|
||||
|
||||
**Date**: 2026-01-11
|
||||
**Workflow**: `.github/workflows/supply-chain-verify.yml`
|
||||
**Status**: ✅ Complete
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Previously, the workflow posted a new comment on each scan run, which meant:
|
||||
|
||||
- Old comments with vulnerabilities remained visible even after fixes
|
||||
- Multiple comments accumulated, causing confusion
|
||||
- No way to track when the scan was last run
|
||||
- Difficult to see the current security state at a glance
|
||||
|
||||
## Solution
|
||||
|
||||
Replaced the `actions/github-script` comment creation with the `peter-evans/create-or-update-comment` action, which:
|
||||
|
||||
1. **Finds existing comments** from the same workflow using a unique HTML comment identifier
|
||||
2. **Updates in place** instead of creating new comments
|
||||
3. **Includes timestamps** showing when the scan last ran
|
||||
4. **Provides clear status indicators** with emojis and formatted tables
|
||||
|
||||
---
|
||||
|
||||
## Changes Made
|
||||
|
||||
### 1. Split PR Comment Logic into Multiple Steps
|
||||
|
||||
**Step 1: Determine PR Number**
|
||||
|
||||
- Extracts PR number from context (handles both `pull_request` and `workflow_run` events)
|
||||
- Returns empty string if no PR found
|
||||
- Uses `actions/github-script` with `result-encoding: string` for clean output
|
||||
|
||||
**Step 2: Build PR Comment Body**
|
||||
|
||||
- Generates timestamp with `date -u +"%Y-%m-%d %H:%M:%S UTC"`
|
||||
- Calculates total vulnerabilities
|
||||
- Creates formatted Markdown comment with:
|
||||
- Status header with appropriate emoji
|
||||
- Timestamp and workflow run link
|
||||
- Vulnerability table with severity counts
|
||||
- Color-coded emojis (🔴 Critical, 🟠 High, 🟡 Medium, 🔵 Low)
|
||||
- Links to detailed reports
|
||||
- Hidden HTML comment for identification: `<!-- supply-chain-security-comment -->`
|
||||
- Saves to `/tmp/comment-body.txt` for next step
|
||||
|
||||
**Step 3: Update or Create PR Comment**
|
||||
|
||||
- Uses `peter-evans/create-or-update-comment@v4.0.0`
|
||||
- Searches for existing comments containing `<!-- supply-chain-security-comment -->`
|
||||
- Updates existing comment or creates new one
|
||||
- Uses `edit-mode: replace` to fully replace old content
|
||||
|
||||
### 2. Comment Formatting Improvements
|
||||
|
||||
#### Status Indicators
|
||||
|
||||
**Waiting for Image**
|
||||
|
||||
```markdown
|
||||
### ⏳ Status: Waiting for Image
|
||||
|
||||
The Docker image has not been built yet...
|
||||
```
|
||||
|
||||
**No Vulnerabilities**
|
||||
|
||||
```markdown
|
||||
### ✅ Status: No Vulnerabilities Detected
|
||||
|
||||
🎉 Great news! No security vulnerabilities were found in this image.
|
||||
```
|
||||
|
||||
**Vulnerabilities Found**
|
||||
|
||||
```markdown
|
||||
### 🚨 Status: Critical Vulnerabilities Detected
|
||||
|
||||
⚠️ **Action Required**: X critical vulnerabilities require immediate attention!
|
||||
```
|
||||
|
||||
#### Vulnerability Table
|
||||
|
||||
| Severity | Count |
|
||||
|----------|-------|
|
||||
| 🔴 Critical | 2 |
|
||||
| 🟠 High | 5 |
|
||||
| 🟡 Medium | 3 |
|
||||
| 🔵 Low | 1 |
|
||||
| **Total** | **11** |
|
||||
|
||||
### 3. Technical Implementation Details
|
||||
|
||||
**Unique Identifier**
|
||||
|
||||
- Hidden HTML comment: `<!-- supply-chain-security-comment -->`
|
||||
- Allows `create-or-update-comment` to find previous comments from this workflow
|
||||
- Invisible to users but searchable by the action
|
||||
|
||||
**Multi-line Handling**
|
||||
|
||||
- Comment body saved to file instead of environment variable
|
||||
- Prevents issues with special characters and newlines
|
||||
- More reliable than shell heredocs or environment variables
|
||||
|
||||
**Conditional Execution**
|
||||
|
||||
- All three steps check for valid PR number
|
||||
- Steps skip gracefully if not in PR context
|
||||
- No errors on scheduled runs or release events
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### 1. **Always Current**
|
||||
|
||||
- Comment reflects the latest scan results
|
||||
- No confusion from multiple stale comments
|
||||
- Clear "Last Updated" timestamp
|
||||
|
||||
### 2. **Easy to Understand**
|
||||
|
||||
- Color-coded severity levels with emojis
|
||||
- Clear status headers (✅, ⚠️, 🚨)
|
||||
- Formatted tables for quick scanning
|
||||
- Links to detailed workflow logs
|
||||
|
||||
### 3. **Actionable**
|
||||
|
||||
- Immediate visibility of critical issues
|
||||
- Direct links to full reports
|
||||
- Clear indication of when action is required
|
||||
|
||||
### 4. **Reliable**
|
||||
|
||||
- Handles both `pull_request` and `workflow_run` triggers
|
||||
- Graceful fallback if PR context not available
|
||||
- No duplicate comments
|
||||
|
||||
---
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
### Manual Testing
|
||||
|
||||
1. **Create a test PR**
|
||||
|
||||
```bash
|
||||
git checkout -b test/supply-chain-comments
|
||||
git commit --allow-empty -m "test: supply chain comment updates"
|
||||
git push origin test/supply-chain-comments
|
||||
```
|
||||
|
||||
2. **Trigger the workflow**
|
||||
- Wait for docker-build to complete
|
||||
- Verify supply-chain-verify runs and comments
|
||||
|
||||
3. **Re-trigger the workflow**
|
||||
- Manually re-run the workflow from Actions UI
|
||||
- Verify comment is updated, not duplicated
|
||||
|
||||
4. **Fix vulnerabilities and re-scan**
|
||||
- Update base image or dependencies
|
||||
- Rebuild and re-scan
|
||||
- Verify comment shows new status
|
||||
|
||||
### Automated Testing
|
||||
|
||||
Monitor the workflow on:
|
||||
|
||||
- Next scheduled run (Monday 00:00 UTC)
|
||||
- Next PR that triggers docker-build
|
||||
- Next release
|
||||
|
||||
---
|
||||
|
||||
## Action Versions Used
|
||||
|
||||
| Action | Version | SHA | Notes |
|
||||
|--------|---------|-----|-------|
|
||||
| `actions/github-script` | v7.0.1 | `60a0d83039c74a4aee543508d2ffcb1c3799cdea` | For PR number extraction |
|
||||
| `peter-evans/create-or-update-comment` | v4.0.0 | `71345be0265236311c031f5c7866368bd1eff043` | For comment updates |
|
||||
|
||||
---
|
||||
|
||||
## Example Comment Output
|
||||
|
||||
### When No Vulnerabilities Found
|
||||
|
||||
```markdown
|
||||
## 🔒 Supply Chain Security Scan
|
||||
|
||||
**Last Updated**: 2026-01-11 15:30:45 UTC
|
||||
**Workflow Run**: [#123](https://github.com/owner/repo/actions/runs/123456)
|
||||
|
||||
---
|
||||
|
||||
### ✅ Status: No Vulnerabilities Detected
|
||||
|
||||
🎉 Great news! No security vulnerabilities were found in this image.
|
||||
|
||||
| Severity | Count |
|
||||
|----------|-------|
|
||||
| 🔴 Critical | 0 |
|
||||
| 🟠 High | 0 |
|
||||
| 🟡 Medium | 0 |
|
||||
| 🔵 Low | 0 |
|
||||
|
||||
---
|
||||
|
||||
<!-- supply-chain-security-comment -->
|
||||
```
|
||||
|
||||
### When Vulnerabilities Found
|
||||
|
||||
```markdown
|
||||
## 🔒 Supply Chain Security Scan
|
||||
|
||||
**Last Updated**: 2026-01-11 15:30:45 UTC
|
||||
**Workflow Run**: [#123](https://github.com/owner/repo/actions/runs/123456)
|
||||
|
||||
---
|
||||
|
||||
### 🚨 Status: Critical Vulnerabilities Detected
|
||||
|
||||
⚠️ **Action Required**: 2 critical vulnerabilities require immediate attention!
|
||||
|
||||
| Severity | Count |
|
||||
|----------|-------|
|
||||
| 🔴 Critical | 2 |
|
||||
| 🟠 High | 5 |
|
||||
| 🟡 Medium | 3 |
|
||||
| 🔵 Low | 1 |
|
||||
| **Total** | **11** |
|
||||
|
||||
📋 [View detailed vulnerability report](https://github.com/owner/repo/actions/runs/123456)
|
||||
|
||||
---
|
||||
|
||||
<!-- supply-chain-security-comment -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Comment Not Updating
|
||||
|
||||
**Symptom**: New comments created instead of updating existing one
|
||||
|
||||
**Cause**: The hidden HTML identifier might not match
|
||||
|
||||
**Solution**: Check for the exact string `<!-- supply-chain-security-comment -->` in existing comments
|
||||
|
||||
### PR Number Not Found
|
||||
|
||||
**Symptom**: Steps skip with "No PR number found"
|
||||
|
||||
**Cause**: Workflow triggered outside PR context (scheduled, release, manual)
|
||||
|
||||
**Solution**: This is expected behavior; comment steps only run for PRs
|
||||
|
||||
### Timestamp Format Issues
|
||||
|
||||
**Symptom**: Timestamp shows incorrect time or format
|
||||
|
||||
**Cause**: System timezone or date command issues
|
||||
|
||||
**Solution**: Using `date -u` ensures consistent UTC timestamps
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Trend Analysis**: Track vulnerability counts over time
|
||||
2. **Comparison**: Show delta from previous scan
|
||||
3. **Priority Recommendations**: Link to remediation guides
|
||||
4. **Dismiss Button**: Allow developers to acknowledge and hide resolved issues
|
||||
5. **Integration**: Link to JIRA/GitHub issues for tracking
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- `.github/workflows/supply-chain-verify.yml` - Main workflow file
|
||||
- `.github/workflows/docker-build.yml` - Triggers this workflow
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment)
|
||||
- [GitHub Actions: workflow_run event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run)
|
||||
- [Grype vulnerability scanner](https://github.com/anchore/grype)
|
||||
Reference in New Issue
Block a user