Charon/docs/implementation/SUPPLY_CHAIN_PR_COMMENTS_UPDATE.md

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

### ⏳ Status: Waiting for Image

The Docker image has not been built yet...

No Vulnerabilities

### ✅ Status: No Vulnerabilities Detected

🎉 Great news! No security vulnerabilities were found in this image.

Vulnerabilities Found

### 🚨 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

   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

## 🔒 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

## 🔒 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
• GitHub Actions: workflow_run event
• Grype vulnerability scanner