# GitHub Star Notifications Setup

> This repository is configured to send push notifications to your phone when someone stars the repository.

- Skill: `tools-only/github-star-notifications-setup` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/github-star-notifications-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/github-star-notifications-setup/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/github-star-notifications-setup

---

# GitHub Star Notifications Setup

This repository is configured to send push notifications to your phone when someone stars the repository.

## How It Works

1. **GitHub Action**: The workflow `.github/workflows/star-notification.yml` triggers on star events
2. **ntfy.sh**: Posts notification to your ntfy topic
3. **Your Phone**: Receive instant notification via ntfy app

## Setup Instructions

### 1. Install ntfy App

**iOS**: https://apps.apple.com/app/ntfy/id1625396347
**Android**: https://play.google.com/store/apps/details?id=io.heckel.ntfy

### 2. Choose Your ntfy Topic

Pick a unique topic name (e.g., `voicemode-stars-mike-bailey-xyz123`). This will be your notification channel.

**Important**: Use a unique, hard-to-guess topic name to prevent others from spamming your notifications.

### 3. Configure GitHub Secret

1. Go to your repository: https://github.com/mbailey/voicemode
2. Navigate to **Settings** → **Secrets and variables** → **Actions**
3. Click **New repository secret**
4. Name: `NTFY_TOPIC`
5. Value: Your chosen topic name (e.g., `voicemode-stars-mike-bailey-xyz123`)
6. Click **Add secret**

### 4. Subscribe in ntfy App

1. Open the ntfy app on your phone
2. Tap the **+** button
3. Enter your topic name (same as the GitHub secret)
4. Tap **Subscribe**

### 5. Test the Notification

You can test the notification manually:

```bash
curl -H "Title: Test Notification" \
     -d "This is a test from your terminal" \
     https://ntfy.sh/your-topic-name
```

Replace `your-topic-name` with your actual topic.

## What You'll See

When someone stars the repository, you'll receive a notification like:

```
Title: VoiceMode ⭐ New Star!
Message: 🎉 username just starred voicemode! Total stars: 400
```

## Customization

Edit `.github/workflows/star-notification.yml` to customize:
- Notification title and message
- Priority level (min, low, default, high, max)
- Tags (for filtering in the app)
- Additional metadata

## Privacy & Security

- **ntfy.sh** is an open-source notification service
- Messages are not encrypted by default (consider self-hosting for sensitive data)
- Use a unique topic name to prevent unauthorized notifications
- No authentication required for basic usage

## Alternative: Self-Hosted ntfy

For enhanced privacy, you can self-host ntfy:

1. Deploy ntfy server: https://docs.ntfy.sh/install/
2. Update the workflow to use your ntfy server URL
3. Add authentication if desired

## Troubleshooting

**Not receiving notifications?**
1. Verify the GitHub secret `NTFY_TOPIC` is set correctly
2. Check you're subscribed to the correct topic in the ntfy app
3. Test with the curl command above
4. Check GitHub Actions logs for errors

**Notifications delayed?**
- GitHub Actions may take 30-60 seconds to trigger
- ntfy delivery is typically instant once the Action runs

## Related Projects

This setup was inspired by the bash-my-aws star notification system, which uses AWS Lambda and Slack. The ntfy approach is simpler and doesn't require AWS infrastructure.