Skip to content
Docs (managed with lightcms)

getting started

This guide walks you through running Newsy and wiring it up to your repositories. There are two methods:

  • Run it locally for development
  • Deploy it to a serverless platform like Vercel for production

A video version of the local setup is available in the greenfield setup guide.

Greenfield deployment

Section titled “Greenfield deployment”

Clone the repository:

Terminal window
git clone [email protected]/pratyay360/newsy.git

We use mise to keep the development environment consistent and easy to manage:

Terminal window
mise deps

Build and run the Go binary:

Terminal window
go build
./newsy

Open http://localhost:3000. Copy that URL into the Webhook URL field when you create the GitHub App (give it a name and continue).

If you hit errors because of local host related issues kindly expose it with a tunneling service such as ngrok, cf-tunnel, zrok2, or simply use ssh with localhost.run if not interested in downloading a separate cli tool.

For example:

Terminal window
ssh -R 80:localhost:3000 localhost.run

Open the url tunnel url in your browser. it should look something like this: if not then watch my video guide or try with a different tunneling service.

Webhook configuration

Create a app name(preferably something unique)

Put the tunnel URL (for example https://xyz.localhost.run) into the webhook urlfield. If everything worked for you, a .env file will be created in your cwd. Keep it safe it contains your app’s secrets.

The generated .env should look something like this:

APP_ID=""
WEBHOOK_SECRET=""
PRIVATE_KEY=""

Important: install the app on specific repositories only not on “all repositories”.

Add these two variables yourself, and make sure the bot is installed on both repositories:

TRACK_REPO=""
DEST_REPO=""
ISSUE_TITLE = "" | optional default: "announcement"
ISSUE_LABEL = "" | optional default: "newsletter"
  • TRACK_REPO — the repository Newsy watches for content changes.
  • DEST_REPO — the repository where newsletter issues are created.

You can set both to the same repository (that’s what I have done in the video).

Repository selection

Deploy on Vercel

Section titled “Deploy on Vercel”

Deploy with Vercel

Once deployed, update your GitHub App’s URLs from *.localhost.run to your apps domain: *.vercel.app.

See the Vercel setup guide for the exact steps.

Only use the deploy button if you already have a GitHub App and remember its credentials. Otherwise, follow the Green field steps first to create one.

Cost of running this

Section titled “Cost of running this”

Vercel offers generous limits for serverless functions also there are many cloud providers offering serverless functions as a service, also you can run the bot on any cloud provider’s serverless runtime — even on the ones that only support JS/TS functions (shh, by compiling the Go code to Wasm with TinyGo).

Because it’s a compiled Go binary, there is no runtime dependencies once built, and it’s memory-efficient, as it’s compiled machine code. You can comfortably stay within invocation memory and duration limits.

Try my newsletter

Section titled “Try my newsletter”

Subscribe to my own newsletter to see it in action:

Subscribe on GitHub

Generate your own button

Section titled “Generate your own button”

Create a subscription button for your account at https://newsy.surge.sh/.

You can style and customize the button using Primer CSS.

Security tip: after the bot publishes its first newsletter issue, lock the conversation so no one else can post in it and exploit your newsletter.

Locking the conversation

Refer to the required permissions page while setting things up.