>

newsy is a newsletter platform for your static site, using GitHub as a backend , inspired by utterances.

Read more about it in the docs.

---

✨ Features

• 📝 Zero-friction publishing — only newly added post files trigger an announcement; edits/deletes are ignored

• 💬 Issue as newsletter — upserts one open issue per repo comments thereafter, with lock and unlocking capability

• Fully free and opensource — no need to pay for any newsletter service, just use your existing GitHub repo.

---

🎬 Demo

Video guides:

---

🚀 Quick start

1. Install the GitHub App on the repo(s) you publish from:

   👉 https://github.com/apps/newsletter-newsy/installations/select_target

2. Push a new post:

   git add posts/hello-world.md
   git commit -m "hello world"
   git push

   newsy will create (or comment on) an open issue titled announcement with label newsletter containing the commit summary, file list, and file contents.

3. Let readers subscribe: generate a button on the site below and drop it into your static site.

---

🧩 Embed a Subscribe button

newsy provides a simple ui to generate your own embeddable button.

1. Enter owner/repo (e.g. acme/example)

2. Copy the embed code:

<a href="https://github.com/OWNER/REPO/issues/42" target="_blank" rel="noopener noreferrer"
   style="display:inline-block;padding:7px 16px;font-size:14px;border-radius:6px;background:#0969da;color:#ffffff;border:1px solid rgba(27,31,36,0.15);font-weight:600;text-decoration:none">
  Subscribe on GitHub
</a>

Drop that into any static site (Hugo, Astro, Next.js, Jekyll, …). Clicking it takes the reader to the issue where they will be able to click Subscribe notifications.

---

🏠 Self hosting

Requirements

• Go & Postgres (for storing the installation id)
• A GitHub App (App ID, private key .pem, webhook secret)
• necessary credentials can be generated by running the application for the first time. If everything happens ideally you should be having a .env file in the root of the current working directory.

1. step 1 Clone

---

git clone https://github.com/Pratyay360/newsy.git && cd newsy

Using mise for managing dependencies is highly recommended.

mise trust      
mise deps

1. Run

---

go build -o newsy && ./newsy
PORT=3000 HOST=0.0.0.0 go run . 

Newsy is written in Go and it runs on serverless systems like vercel, google cloud run etc which supports go based serverless functions. You can also run it on other platforms which only supports nodejs based runtime by building a wasm of newsy.

1. Expose webhooks locally

---

Set WEBHOOK_PROXY_URL (for example, Smee.io) so GitHub can reach your localhost: you can get yours at https://smee.io/new.

WEBHOOK_PROXY_URL=https://smee.io/xxx go run .

Or use any tunnel like ngrok or cloudflared or localhost.run to expose your local server to the internet.

🤝 Contributing

• kindly star the repo,
• open issues report bugs
• PRs are always welcome.
• support me financially

📄 License

Licensed under the Apache-2.0.

---

💎 Acknowledgements

• utterances — inspiration for using GitHub Issues as app data
• probot-go — Go port of Probot
• go-github — GitHub API client
• zerolog — structured logging
• Primer CSS — docs UI