Issues Tracking

import { Aside, Steps } from ‘@astrojs/starlight/components’;

Overview

Issues are tracked in two places:

1. GitHub Issues — source of truth (create and manage all issues here)
2. ISSUES.md — auto-generated snapshot committed to the repository, updated by GitHub Actions

---

Automated Sync Workflows

Three workflows keep ISSUES.md in sync:

Workflow	File	Trigger
Primary sync	.github/workflows/sync-issues.yml	Daily 9 AM UTC, issue events, manual
CI integration	.github/workflows/ci.yml (sync-issues job)	After successful build on main/develop
Reusable	.github/workflows/reusable-sync-issues.yml	Called from other workflows

What the sync does

1. Fetches all issues (open + closed) from the GitHub API
2. Groups by milestone (M1–M8)
3. Generates a progress bar per milestone
4. Writes/updates ISSUES.md
5. Auto-commits with [skip ci] to prevent recursive builds

Preventing infinite loops

All sync commits include [skip ci] in the message:

chore: sync issues tracker
[skip ci]

---

ISSUES.md Format

# Issues Tracker

## Summary
| Status | Count |
|--------|-------|
| Open   | 22    |
| Closed | 8     |

## M1 — Brand Foundation & Design System
Progress: ████████░░░░░░░░░░░░ 40% (2/5)
- [🔴 Open]   #5 [M1-T2] Select and license typography…
- [✅ Closed] #3 [M1-T1] Define color palette…

• █ = closed issues
• ░ = open issues
• 🔴 Open / ✅ Closed status icons

---

Issue Best Practices

Always assign a milestone

Title:     [M1-T2] Select and license typography pairing
Milestone: M1 — Brand Foundation & Design System

Use consistent labels

Label	Color	Purpose
roadmap	#6366f1	Part of tracked milestone roadmap
M1–M8	Per milestone	Milestone label
design	#EC4899	Design/visual task
content	#F59E0B	Copy/content work
blocked	#6B7280	Blocked — needs resolution
bug	#EF4444	Bug report

Link dependent issues

Depends on: #5
Blocks: #12

---

Using the Reusable Workflow

Call from any other workflow to sync issues after deployment or release:

jobs:
  deploy:
    # ... your deploy steps

  sync-issues:
    uses: ./.github/workflows/reusable-sync-issues.yml
    needs: deploy
    with:
      commit_message: "chore: sync issues after deployment"

---

Troubleshooting

Issues not updating?

• Confirm GitHub Actions is enabled in repository Settings → Actions
• Check that the workflow has contents: write permission
• View run history: Actions → Sync Issues to File

ISSUES.md not committed?

• Verify contents: write in workflow permissions block
• Check that there are actual changes to commit (sync is a no-op if nothing changed)

The `ISSUES.md` file is not a substitute for GitHub Issues — it's a read-only snapshot for quick reference in the repository. Always create and close issues in GitHub.

---

Milestone Reference

Issues are grouped by these milestones:

Milestone	Description
M1 — Brand Foundation	Design system, typography, component library
M2 — Infrastructure	Vercel, Supabase, Cloudflare, CI/CD
M3 — Core Pages	Hero, About, Services, Testimonials, Footer
M4 — Booking System	Inquiry form, Supabase, Resend, HubSpot, Calendly
M5 — Media Kit	Press portal, R2 storage, email gate
M6 — Podcast	RSS, episode player, archive page
M7 — SEO & Performance	OG images, sitemap, Lighthouse ≥ 90
M8 — Launch	Content sign-off, domain cutover, monitoring

Issues without a milestone appear in a “No Milestone” section at the bottom of ISSUES.md.