GitHub Release Watcher

Never miss an important software release again. This OpenClaw agent monitors GitHub repositories for new releases and instantly notifies you when your favorite projects ship updates.

What It Does

GitHub Release Watcher tracks any number of GitHub repositories and sends you real-time alerts when:

• New releases are published
• Pre-releases and release candidates drop
• Security updates are tagged
• Major version bumps occur

Perfect for developers, DevOps engineers, and anyone who needs to stay on top of dependency updates, security patches, or ecosystem changes.

Key Features

• Automatic monitoring — Checks your watchlist every 30 minutes via heartbeat
• Smart notifications — Only alerts on new releases, never spam
• Rich release info — Version, changelog, download links, author
• Flexible filtering — Watch all releases or major versions only
• Manual checks — Ask "check releases" anytime for instant updates
• Persistent memory — Remembers what you've already been notified about
• GitHub API optimized — Respects rate limits (5,000 req/hour authenticated)

Quick Start

# Install from Hatchery
hatchery run @openclaw/github-release-watcher

# Set your GitHub token (optional but recommended for higher rate limits)
export GITHUB_TOKEN=ghp_your_token_here

# Add repositories to watch
"Watch torvalds/linux for releases"
"Add watch for nodejs/node"
"Monitor docker/compose"

# The agent checks every 30 minutes automatically
# Or ask manually: "check for new releases"

Configuration

Required Environment Variables

None! The agent works with GitHub's public API.

Optional Environment Variables

# Highly recommended: Increases rate limit from 60/hour to 5,000/hour
GITHUB_TOKEN=ghp_your_personal_access_token

# Optional: Your timezone for time-aware notifications
USER_TIMEZONE=America/New_York

Get a GitHub token:

1. Go to https://github.com/settings/tokens
2. Generate new token (classic)
3. Select scope: public_repo (read-only access)
4. Copy token to your .env file

Customizing Your Watchlist

Edit memory/watchlist.json to pre-configure repositories:

{
  "repositories": [
    {
      "owner": "nodejs",
      "repo": "node",
      "filter": "major"
    },
    {
      "owner": "docker",
      "repo": "compose",
      "filter": "all"
    }
  ]
}

Filter options:

• all — Every release and pre-release
• major — Only major version bumps (v2.0.0, v3.0.0, etc.)
• stable — Only stable releases (no pre-releases or RCs)

Usage Examples

Add a Repository

You: Watch kubernetes/kubernetes for releases
Agent: ✅ Now watching kubernetes/kubernetes. I'll check every 30 minutes and notify you of new releases.

Manual Check

You: Check for new releases
Agent: Checking 5 repositories...

🚀 New release found!

**kubernetes/kubernetes v1.29.0**
Released 2 hours ago by @liggitt

📝 Changelog highlights:
- New feature: XYZ
- Security fix: CVE-2024-1234
- Breaking change: ABC

🔗 https://github.com/kubernetes/kubernetes/releases/tag/v1.29.0

List Watched Repos

You: What repos are you watching?
Agent: I'm currently monitoring 5 repositories:
- nodejs/node (major versions only)
- docker/compose (all releases)
- kubernetes/kubernetes (stable only)
- torvalds/linux (all releases)
- rust-lang/rust (major versions only)

Remove a Repository

You: Stop watching torvalds/linux
Agent: ✅ Removed torvalds/linux from watchlist.

How It Works

Architecture

1. Heartbeat monitoring — Every 30 minutes, the agent:

   • Loads your watchlist from memory/watchlist.json
   • Fetches latest release for each repo via GitHub API
   • Compares against last known versions in memory/release-state.json
   • Notifies you of any new releases
   • Updates state file

2. GitHub API integration — Uses the /repos/{owner}/{repo}/releases/latest endpoint

   • Authenticated: 5,000 requests/hour
   • Unauthenticated: 60 requests/hour
   • Smart caching prevents redundant API calls

3. State tracking — Persistent memory ensures you never get duplicate notifications

Files

• HEARTBEAT.md — Defines the 30-minute check routine
• skills/github-release/ — GitHub API integration skill
• memory/watchlist.json — Your monitored repositories
• memory/release-state.json — Last known release versions
• MEMORY.md — Agent's knowledge about releases and your preferences

Troubleshooting

"Rate limit exceeded" error

Problem: You're hitting GitHub's 60 req/hour limit for unauthenticated requests.

Solution: Add a GITHUB_TOKEN to your .env file (increases limit to 5,000/hour).

Not receiving notifications

Problem: Agent checks every 30 minutes — if a release happened 10 minutes ago, you'll get notified in 20 minutes.

Solution: Ask "check for new releases" to trigger an immediate check.

Missing a repository I added

Problem: Watchlist wasn't saved properly.

Solution: Check memory/watchlist.json to verify the repo is listed. The format should be:

{"owner": "username", "repo": "reponame", "filter": "all"}

Agent says "Repository not found"

Problem: Typo in owner/repo name, or repository is private.

Solution: Verify the exact owner and repo names on GitHub. Private repos require a token with appropriate permissions.

Advanced Configuration

Adjusting Check Frequency

Edit HEARTBEAT.md and change the interval:

### Release Check (every 30 minutes)  →  (every 60 minutes)

Restart the agent for changes to take effect.

Custom Notification Format

Edit AGENTS.md under "Release Alert Format" to customize how releases are announced.

Filter by Tag Pattern

You can add custom regex filters in memory/watchlist.json:

{
  "owner": "nodejs",
  "repo": "node",
  "filter": "all",
  "tagPattern": "^v[0-9]+\\.[0-9]+\\.0$"
}

This would only match v20.0.0, v21.0.0 (major releases), ignoring v20.1.3.

Security & Privacy

• API token security: Your GITHUB_TOKEN never leaves your machine — stored in .env only
• Read-only access: The agent only reads public release data, never writes to GitHub
• No data collection: All state stored locally in your workspace

Use Cases

• Dependency monitoring — Track libraries your project depends on
• Security alerts — Get notified immediately of security patch releases
• DevOps pipelines — Trigger deployments when new stable releases drop
• Open source maintainers — Keep tabs on related projects in your ecosystem
• Technology radar — Stay current with rapidly evolving tools (Kubernetes, Docker, Rust, etc.)

Contributing

This template is open source. Contributions welcome!

• Report issues or request features on GitHub
• Submit pull requests to improve the agent
• Share your customizations with the community

License

MIT License — free to use, modify, and distribute.

---

Built with OpenClaw — The self-hosted AI agent runtime for Claude.
Published on Hatchery — The package manager for OpenClaw agents.

Need help? Join the OpenClaw community on Discord.