diff --git a/.github/workflows/shared/asset-discussion-pattern.md b/.github/workflows/shared/asset-discussion-pattern.md new file mode 100644 index 0000000000..9fd0f248b1 --- /dev/null +++ b/.github/workflows/shared/asset-discussion-pattern.md @@ -0,0 +1,224 @@ +--- +# Asset Upload and Discussion Creation Pattern +# Standardized workflow for uploading charts/assets and embedding in discussions +--- + +# Asset Upload and Discussion Creation Pattern + +This shared component provides a standardized pattern for workflows that generate visualizations or other assets and publish them in GitHub Discussions. + +## Prerequisites + +Your workflow must have safe-outputs configured: + +```yaml +safe-outputs: + upload-asset: + create-discussion: + category: "General" # or "audits", "reports", etc. + max: 1 + close-older-discussions: true # Optional: close previous reports + expires: 3d # Optional: auto-close after 3 days +``` + +## Standard Workflow Pattern + +### Phase 1: Generate Assets + +Generate your charts, images, or other assets: + +```bash +# Example: Generate charts with Python +python3 /tmp/gh-aw/python/generate_charts.py + +# Verify assets exist +ls -lh /tmp/gh-aw/python/charts/*.png +``` + +**Chart Quality Standards** (for image assets): +- **DPI**: 300 minimum +- **Figure Size**: 12x7 inches (or appropriate for content) +- **Format**: PNG with transparent or white background +- **File Size**: < 5MB recommended + +### Phase 2: Upload Assets + +Upload each asset and collect the returned URLs: + +```bash +# Upload assets using the upload asset tool +# The tool returns a URL for each uploaded file + +# For each chart/asset: +# 1. Call: upload asset with path /tmp/gh-aw/python/charts/chart1.png +# 2. Collect the returned URL (e.g., https://raw.githubusercontent.com/...) +# 3. Store URL for use in discussion markdown + +# Example workflow: +# - Upload chart1.png → Get URL1 +# - Upload chart2.png → Get URL2 +# - Upload chart3.png → Get URL3 +``` + +**Important Notes**: +- Asset URLs are published to an orphaned git branch +- URLs become accessible after workflow completion +- Assets persist indefinitely (no expiration) +- Use descriptive filenames (e.g., `issue_activity_trends.png` not `chart1.png`) + +### Phase 3: Create Discussion with Embedded Assets + +Create a discussion with embedded asset URLs: + +```markdown +# Example Discussion Body + +Brief 2-3 paragraph summary of key findings. + +## 📊 Visualizations + +### Chart 1: Descriptive Title +![Chart 1](URL_FROM_UPLOAD_ASSET_1) + +[2-3 sentence analysis of what the chart shows] + +### Chart 2: Descriptive Title +![Chart 2](URL_FROM_UPLOAD_ASSET_2) + +[Analysis of second chart] + +## Summary + +Key takeaways and action items. + +--- +*Report generated by [Workflow Name] workflow* +*Run: [${{ github.run_id }}](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})* +``` + +## Discussion Configuration Best Practices + +### Title Formatting + +Use descriptive, dated titles: +- **Good**: `Daily Code Metrics Report - 2026-01-20` +- **Good**: `[daily-issues] Issue Analysis - 2026-01-20` +- **Avoid**: `Report`, `Analysis` (too generic) + +### Category Selection + +Choose appropriate categories: +- **`General`**: Informational reports, summaries +- **`audits`**: Security, compliance, health checks +- **`reports`**: Data analysis, metrics, trends +- **`Q&A`**: Question-based reports requiring response + +### Close Older Discussions + +For daily/weekly reports, use `close-older-discussions: true`: +- Keeps discussions clean (only latest visible) +- Previous reports remain accessible via search +- Reduces notification noise + +### Expiration + +Set `expires` for time-sensitive reports: +- **`expires: 3d`**: Daily reports (closed after 3 days) +- **`expires: 7d`**: Weekly reports +- **No expiration**: Permanent reference reports + +## Common Patterns + +### Pattern 1: Multiple Charts with Analysis + +```markdown +## 📊 Visualizations + +### Chart Title 1 +![Chart 1](URL_1) +[Analysis] + +### Chart Title 2 +![Chart 2](URL_2) +[Analysis] + +## Summary +Key findings and recommendations. +``` + +### Pattern 2: Single Hero Chart + Details + +```markdown +## Overview + +![Main Chart](URL_1) + +[2-3 paragraph analysis of the main chart] + +## Details + +Additional context and findings. +``` + +### Pattern 3: Comparison Charts + +```markdown +## Comparison Analysis + +| Metric | Current | Previous | Change | +|--------|---------|----------|--------| +| X | 100 | 90 | ⬆️ +11% | + +### Trend Visualization +![Trend Chart](URL_1) + +### Distribution Comparison +![Distribution Chart](URL_2) +``` + +## Troubleshooting + +### Asset URLs Not Working + +**Problem**: Markdown shows broken image icon +**Solution**: +- Verify upload asset tool returned success +- Check URL format (should be `https://raw.githubusercontent.com/...`) +- Wait for workflow to complete (assets publish at end) +- Verify file exists at uploaded path + +### Discussion Not Created + +**Problem**: Workflow completes but no discussion appears +**Solution**: +- Check safe-outputs.create-discussion is configured +- Verify category exists in repository +- Check max limit not exceeded +- Review workflow logs for errors + +### Charts Not Displaying Correctly + +**Problem**: Charts too small, blurry, or distorted +**Solution**: +- Use DPI 300 minimum +- Set appropriate figure size (12x7 recommended) +- Save with `bbox_inches='tight'` +- Use PNG format, not JPEG + +## Examples + +See these workflows for complete implementations: +- `daily-code-metrics.md` - 6 charts with trend analysis +- `daily-issues-report.md` - 2 charts with clustering +- `copilot-session-insights.md` - Session activity charts + +## Migration Checklist + +To adopt this pattern in an existing workflow: + +- [ ] Configure `safe-outputs.upload-asset` and `safe-outputs.create-discussion` +- [ ] Generate assets to standard path (e.g., `/tmp/gh-aw/python/charts/`) +- [ ] Upload each asset and collect URLs +- [ ] Create discussion body with embedded image markdown +- [ ] Test workflow to verify assets display correctly +- [ ] Verify old discussions close if `close-older-discussions: true`