Newsfeed and Events

Two plain, black pages built from the same code:

• Newsfeed, the latest posts, podcast episodes and videos from a few sites, newest first: https://news.grahamhagenah.com/
• Events, concerts over the next 60 days (venues announce them further ahead) and films, and art and talks, over the next 30, grouped by day (MUSIC_DAYS_AHEAD and DAYS_AHEAD in events/build.py): pushpin.city, a site for each city. events.grahamhagenah.com was this page before Pushpin had a site of its own; it now holds the listings each build keeps for the next one (listings.json) and a page sending readers on to Pushpin Boston.

What's where

• news/: the newsfeed. feeds.txt lists its sites; build.py reads their feeds (and links podcast episodes to Apple Podcasts); sources.py is the bot behind the "Add a site" page.
• events/verify/ is published at pushpin.city's root as it is, for a file a service asks for to know the site is ours (Google Search Console's googleXXXX.html).
• events/: the events page. sources.txt lists its venues and how to read each (Boston's; sources-westernma.txt and sources-bayarea.txt for the other cities); skip.txt has words and phrases that keep a listing off both events pages when its name has one ("comedy"), except films; build.py has a reader for each kind of source and combines a film showing at several theaters into one row; find_venue.py looks up Ticketmaster venue ids.
• shared/: what both use. site.py has the page around each list (head, header, the styles they share, icons, the script that ages timestamps), fetching with retries, and the fallback and failure bookkeeping; alerts.py opens and closes "Source failing" issues.
• jobs/: the job board. sources.txt lists the boards and the city each covers; keywords.txt the titles worth listing; build.py reads each board.
• housing/: the housing tracker. build.py reads Boston's and Cambridge's lists of development projects, and MassBuilds for the towns around them; edits.txt holds our own changes to them and projects they don't list.
• tests/: each page's readers against saved samples of real sources (tests/fixtures/news, tests/fixtures/events), the fallback rules, and the shared page and alerts.

Run everything from this top folder, with only the Python standard library:

• python3 -m news.build and python3 -m events.build write dist/news and dist/events; open their index.html. python3 -m housing.build writes dist/housing, python3 -m jobs.build writes dist/jobs.
• python3 -m unittest runs the tests.

The newsfeed

• Add or remove sites from the sources page, which opens a pre-filled issue that the sources.yml workflow applies to news/feeds.txt, or edit that file directly. A homepage URL is enough; the build finds the feed. Options like limit=5, days=14 and only="Full Performance" (only posts whose titles have that in them) go at the end of a line, and apple=<id> ties a podcast to its show in Apple Podcasts when the feed address Apple has on file isn't the one here.

• YouTube channels work like any site (a channel's page is enough). Their videos, and any post linking straight to a YouTube video, play on the page in YouTube's privacy-enhanced embedded player, in a plain window that closes when the video ends, before YouTube can suggest another. A video opens in a corner of the screen, small, where it plays on while the list is read and scrolled behind it, and can be dragged anywhere by the bar across its top, which also holds a button that copies the video's own address (the video itself is YouTube's own page, which answers every press inside it). The whole screen is YouTube's own full-screen button, in its controls: it takes its frame there and hands it back to the corner afterwards, still playing, where asking for the screen ourselves meant a second player, a second set of rules for phones that won't grant it, and a window that remembered where it had been dragged to while it filled the screen. Its controls fade out on their own when the pointer leaves, so the corner is quiet most of the time. Shorts are left out. Hold a modifier key while clicking to open YouTube instead. YouTube's channel feeds sometimes answer 404 for a while; with a free YouTube Data API key kept as this repo's YOUTUBE_KEY secret, a channel whose feed fails comes from the API instead (its uploads without Shorts, one of the key's 10,000 daily units a request).

• Make your own (/make-your-own/, linked from the sources page) walks someone else through setting up a newsfeed of their own, from the grahamhagenah/newsfeed template: that's this newsfeed's code on its own — news/, shared/, their tests, a starter feeds.txt and a workflow that builds and publishes it — written by python3 -m news.template <folder>, which checks its tests and a build pass inside the copy before it's published. template.yml keeps the template repo in step whenever the newsfeed's code changes here, given a TEMPLATE_TOKEN secret (a fine-grained token with Contents: read and write on that repo); without one it says so and stops. The newsfeed takes the repo it belongs to and the address it's published at from the environment (, ), so a copy points at its own repo for Add a site and its own page for the last build's posts, and names a sister site in the header only where is set — which this repo's workflow does, and a copy doesn't.

The job board

Web and design jobs around a few metro areas, newest first, at https://grahamhagenah.github.io/jobs/ (pushed to the grahamhagenah/jobs repo's gh-pages branch, as the other pages are to theirs, with JOBS_DEPLOY_KEY). It rebuilds every two hours (JOBS_EVERY_HOURS), since boards list the same openings all day.

• The cities are the metros in CITIES (jobs/build.py), and Remote, which is a city here: a job belongs to whichever source listed it. The menu over the list chooses one (?city=), the filter beside it chooses engineering, design or remote work, and the search looks through everything on the page, as the newsfeed's does.
• Sources are in jobs/sources.txt: how to read each, its address, its city, and its name. Built In has a site per metro (Boston, NYC, SF, Seattle, Colorado, Chicago, Austin, LA) whose robots.txt allows its job pages; its engineering and design listings give each job's company, where it is, what it pays, how it's worked and how senior, and the schema.org list on the same page gives the description. Remote jobs come from We Work Remotely's feeds, Remote OK's JSON (its terms ask for the link back, which every listing is) and Remotive's, which answers the same latest jobs whatever category is asked for, so it's read once.
• Only titles matching jobs/keywords.txt are listed — web, design, UI, UX, developer, JavaScript and the like — so a board's other openings stay off the page. A posting older than DAYS_TO_KEEP (30 days) is dropped, and no board gives more than PER_SOURCE.
• An employer posting the same opening to every Built In metro is one row that belongs to all of them: choosing a city still finds it, its place reads "8 cities", and merging keeps whatever one copy says and another doesn't (the pay, how senior, the newer day). That turns the most common repeat, about 200 rows a build, into one each.
• A board that fails falls back to its jobs from the last build for up to two days (board.json, the same bookkeeping the other pages use), and the page says so.

The events page

• Venues rarely publish feeds, so the build uses the most dependable thing each offers: AEG's event data (Roadrunner, and Royale out of Bowery Presents' Boston feed, which books a dozen venues), an AXS venue site's full listing and its shows' own pages for start times (The Sinclair), schema.org event data (the Brattle, House of Blues, Deep Cuts' page on DICE), a calendar feed (Midway Cafe, and Arts at the Armory's, sorted by its own categories), a Squarespace site's event data (The Lilypad), a calendar in a page's script (Club Passim), a WordPress calendar's API (Lizard Lounge, The Rockwell's music), the schedule data behind a theater chain's site (Alamo Drafthouse, Landmark's Kendall Square), Ticketmaster (the Paradise, Brighton Music Hall, the Crystal Ballroom), a Veezi-hosted theater's own data (West Newton Cinema), a cinema's schedule on the ticketing site it books through (the Lexington Venue, on Jacro's TaPoS), a theater's own site and ticketing together (the Somerville Theatre and the Capitol, below), or the page itself (the Coolidge, the Harvard Film Archive, TicketWeb listings at the Middle East).
• The Somerville Theatre and its sister the Capitol gave permission to read their sites (October 2026), which they otherwise turn away: the build names itself PushpinBot to them, as fetch's user_agent lets a source do. Both run WordPress's Theater plugin and book through Jacro's TaPoS, so one reader (wptheatre) does the pair. A site's productions give each film or show its name, description, poster and page — "Ken Russell's The Devils" where the ticketing says only "The Devils" — and say whether it's a film (the Somerville Theatre files them under "movie", the Capitol under "movies") or a live show, so a film with an orchestra is filed as a film. A theatre's events page gives concerts and the like their days and times; the Capitol shows only films and has no such page, which it says with a 404, where any other answer is the source failing. A film's times are only on the film's own page, which would be a fetch per film every build, so those come from the ticketing each books through (CSBSOM and CSBARL, the same sales their own pages send readers to), leaving three fetches a build for everything a theatre is showing. A name is matched to the nearest of the site's holding it, so the Somerville Theatre's ticketing's "House" is its site's "House (Hausu)" and not its "House on Haunted Hill"; anything on both an events page and the showtimes is listed once.
• Art & talks come from MIT's events calendar (public exhibitions, and talks from its architecture and humanities schools or listed under the arts), the Boston Public Library's events feed (talks, lectures and exhibitions for adults), the MFA's and Harvard Art Museums' calendars (their lectures, talks and special events; their films go under Film), SoWa's First Fridays, the ICA's talks, dance and First Fridays (its concerts go under Music, its films under Film), the French Library's talks and screenings (its screenings go under Film), and ArtsEmerson's performances. An exhibition is listed on the day it opens, with when it closes.

Pushpin, the public version

Pushpin has a site for each city at a path of its own on pushpin.city: Pushpin Boston at /boston/, Pushpin Western Mass at /westernma/ (the Pioneer Valley and the Berkshires), and Pushpin Bay Area at /bayarea/ (San Francisco and Oakland). Venues to consider for the Bay Area are in events/bayarea-venues.md. Each city is a City in events/build.py (CITIES): its slug (its folder, and its sources file, sources-<slug>.txt; Boston's is sources.txt), its name, its state (which the cities page lists it under) and its clock (zone: what time its listings' times are in — Pacific for the Bay Area, so an 8pm show reads 8pm and its calendar entry says so; the page carries it as ZONE, which is what its script means by today, tomorrow, and what's already started), and what its pages say, every city's from city_texts (its name, its place for titles, "Western Mass", and where it covers for the rest, "the Pioneer Valley and the Berkshires"), with kinds giving a kind's page its own title, description or tagline where the shared words are too plain for it (Boston's film page: "Movie showtimes and repertory film in Boston"). The PUBLIC_ names are whichever city's pages are being written; they start at Boston's and use_city points them at each in turn. One build reads every city's sources; the personal events page shows only Boston's, and its listings.json keeps every city's to fall back on. Each city's pages are then written in turn (write_city), with use_city pointing the PUBLIC_ names at it. The site's root lists the cities under the state each is in, with where it covers (render_cities, a City's state and around; its header and the line under it the same as a city's pages'), then any being worked on (COMING_SOON) and a way to ask for another. One contact form serves every city, at /contact/ (render_contact), which each city's footer and About page link to and its old /<city>/contact/ sends on to; the root's own pages are built by site_page, with a city's header and styles, and listed in its own sitemap.xml, its 404 page sends an address under a city's folder to that city (a passed listing's to its view) and any other, from before there were cities, to the same under Boston's (render_not_found), and its robots.txt names each city's sitemap. Each city's footer links to the root ("All cities"). Its About page leaves out Boston's question about the Capitol Theatre.

To add a city: add a City to CITIES (with city_texts), a sources-<slug>.txt, its venues' addresses to VENUE_ADDRESSES, and its cards to CARDS in share_cards.py, then run python3 -m events.share_cards.

Western Mass's venues, from surveys of independent ones there (the Pearl Street Ballroom looked closed; the Clark, Jacob's Pillow and Williams College (its '62 Center and events calendar) block automated visits; Hawks & Reed's calendar has had nothing on it since 2021; Tanglewood's season is the summer's, and the BSO's calendar is built in the browser from a search service, so it waits for spring):

• Mass MoCA (massmoca): its WordPress calendar (The Events Calendar, the tribe reader), sorted into our kinds by its own categories (MASS_MOCA_KINDS: concerts; book and artist talks, performances, public programs and exhibition openings), not Kidspace's storytimes. Its titles set a subtitle in a lighter span, sometimes left open ("Madison Cunningham <span class="title-light">Ace Tour"), which becomes the listing's detail (tribe_title, for every Events Calendar site). Its long-running exhibitions, open for years, are left out.
• Amherst Cinema (amherstcinema): a calendar page for each day, /calendar/month/2026-09-16 despite its name, each film with its series and times, and each film's own page for its picture and description (not its notes for particular days, "On Tuesday 9/15, the 2:10 showtime is presented with Open Captions").
• Images Cinema and the Triplex (indy): both run on Indy Systems, whose pages are an app that asks its GraphQL API for showings, one day at a time; the API answers only for the theater the request names, as the app does, with client-type: consumer and the theater's site and circuit ids, which go in the source's URL (?site=57&circuit=49, Images'; ?site=115&circuit=76, the Triplex's). A showing with no seats left is sold out.
• The Iron Horse and the Parlor Room (elfsight): one calendar for both, an Elfsight Event Calendar widget on the Iron Horse's site, read from the data the widget loads (its boot address, with the page and the widget's id). Each source keeps the shows in the room its name names (THE PARLOR ROOM for Parlor Room), not its kids' events, musician's workshops or open mics (ELFSIGHT_SKIP, by event type), or ones that repeat. Its price line ("TIX START @ $42 incl. all fees") gives the price, and a SOLD OUT button, sold out. Its shows elsewhere (the Shea Theater, Black Birch Vineyard) could be sources too, named for those rooms.
• The Drake (squarespace), like the Lilypad. A show's supporting acts, after its name ("MINI TREES - w/ Frown Line"), become its detail ("with Frown Line", with_support), for Squarespace and Elfsight venues.
• The Mahaiwe (mahaiwe): its calendar feed, by its categories (MAHAIWE_KINDS: concerts and opera; films and its HD broadcasts; lectures), not its comedy or dance classes. Its Indigo Room's shows, next door, are the Mahaiwe's, saying Indigo Room.
• The Shea Theater (shea, Turners Falls): its calendar, a month's grid to a page, each show's picture at an address from its id. "Shea Presents:" comes out of a name; another presenter ("DSP Shows Presents: Beth Orton") becomes the detail ().

Pushpin Boston

The events build also writes the same listings for anyone, as Pushpin Boston (dist/public), published from the grahamhagenah/pushpin repo's gh-pages branch at https://pushpin.city/boston/ (four A records for pushpin.city point at GitHub Pages, a CNAME record for www at grahamhagenah.github.io). Each city gets a path of its own there (PUBLIC_URL); the site's root lists the cities (above). It was first published as Boston, Daily at boston.grahamhagenah.com, whose pages now send each old address on to the same page here, keeping any ?venue= or ?q= (python3 -m events.moved, published once from the grahamhagenah/boston-daily repo). It has its own name in place of the Newsfeed/Events switcher, an About page (what it is, and every venue), the site's Contact form, a footer listing every page (Browse: all events and each kind; When: tonight and the weekends; About and Contact) with the current one marked (public_footer), each page's own line over its listings (the film page's, "Films around Boston, Cambridge, and Somerville, from repertory screenings to new releases…"; the home page's, the site in short, PUBLIC_SHORT), and what the site is in full at the foot of every page (public_footer, PUBLIC_TAGLINE), shorter previews of the venues' own descriptions (all of one in a listing's view), no "Add a source" link, and lets search engines list it.

• For search engines: a descriptive title and description, a one-line tagline, a canonical address, sharing tags, every listing as schema.org event data (with each venue's street address, from VENUE_ADDRESSES in events/build.py unless the source gives the event's own, so add a new venue's there), a sitemap.xml and a robots.txt pointing to it.
• Each kind has its own page, /boston/music/, /boston/film/ and /boston/talks/, with only its events and its own title, description and tagline (PUBLIC_PAGES in events/build.py). The filter's choices link to them; on the home page, which has every event, the filter shows a kind in place and puts its page's address in the address bar. The pages link to each other from the city's root (/boston/about/), since a relative link would go astray after that.
• /boston/tonight/ lists what's still to come today, on one page (PUBLIC_TONIGHT). It holds tomorrow's listings too and shows only the day it is where it's read, so it rolls over at midnight rather than waiting up to three hours for the next build.
• /boston/weekend/ lists Friday to Sunday: the weekend it is, or from Monday to Thursday the one coming (weekend_days), and /boston/weekend/next/ the weekend after; each shows the whole weekend on one page and links to the other where the pager would be (PUBLIC_WEEKENDS). Their filter shows a kind in place. Every public page's footer links to this weekend's.
• Its visits are counted with GoatCounter; see Visitor counts.
• Calendars to subscribe to, which each build writes to /boston/calendar/: one for each kind (music.ics, film.ics, talks.ics) and one for each venue (the-sinclair.ics), of what's coming up (calendar_feeds). Each listing is one event, at its first time for two hours or all day without one, its other times in its notes, with an id that stays the same from build to build so a calendar app updates it rather than adding it again. The About page's Calendars section links each kind's for Apple Calendar (webcal://) and Google Calendar; the footer links there too. The venues' own feeds are still written, for anyone already subscribed, but no longer linked (webcal:// does nothing in most desktop browsers).
• A listing's view has a Copy link button, rather than the device's share sheet: it copies the listing's own link, and says "Link copied" with a check for a moment. That link is the listing's own small page, (, about 900 a build), whose preview in iMessage, Slack and the like is the event's: a title saying what it is, where and when (: "Showtimes for Akira (4K Restoration) at Coolidge Corner · Tue, Sep 15", "Telescreens at The Rockwell · Fri, Sep 18, 7pm"; iMessage shows only the title and picture), a line with the venue, day, times, price (or Sold out) and ages, and its own picture, or its kind's card when it has none. Apps that show previews don't run scripts, so the home page's address would preview as the home page. Someone who opens it goes straight on to the listing's view; once it's passed, its page is gone, and the site's 404 page sends the link on to its view, which opens the next of its series. The pages aren't listed by search engines. Copied links are counted in GoatCounter as , as shares were.

The housing tracker

Build Housing Boston: new housing being proposed, approved and built around Boston, at buildhousing.org: a map of it, then a list for each town, newest news first. A project opens in a panel (a sheet on a phone), as Pushpin's listings do, with what its source says about it: its dates, cost, size, developer and description, our note, and for Boston's projects the rendering from its page on bostonplans.org, which each build looks up only for projects it hasn't seen before (images in projects.json). Its address (?project=boston-4930) links straight to it. A page carries none of the panels' details: they're in panels.json, the same for every page, asked for as a project is about to be opened (when the reader first points at a row, or once the page is quiet). The map's library, a megabyte, is fetched only as the map comes near the window. Over the map, a Recently updated line turns over the newest changes, as Pushpin's Just announced does, and leads to Recent updates (/recent/): every project with something that happened in the last RECENT_DAYS days (90; the cities refresh their lists every few weeks or months), newest first, each saying what: a status seen to change ("Proposed → Approved", or "Newly listed"), a Boston filing or board approval, an update in MassBuilds, or our own note. The map is MapLibre's (from cdnjs), on OpenFreeMap's dark vector tiles, which need no key; the browser draws their roads and names itself, so they're sharp on any screen. The map draws every project at the zooms a reader starts at, so a town with little going on looks that way because it is; only further out, where the whole region is in view, does it leave the smaller ones out (40 homes or more, then 120 at its farthest), with a note in its corner saying so. A search, Recent updates and Large projects always show every one. Large projects (/large/) lists those of LARGE_HOMES homes or more (300) across every town, biggest first, each with a bar of four steps (proposed, approved, under construction, complete) showing how far along it is. Have your say (/have-your-say/) lists Boston's open comment periods and upcoming public meetings, soonest first: each comment period from its project's page on bostonplans.org ("Comment period ends Sep 30, 2026"), read each build for projects under review or filed in the last 120 days; each meeting from the Planning Department's calendar feed, whose descriptions link to the projects they're about. A project's panel lists its own in a Have your say box, its row carries a tag with the soonest, and a line under Recently updated shows the soonest of all. Cambridge's are its Planning Board's meetings, from its table of what's scheduled for each, whose items name the case numbers (PB-410) the development log gives for each project; its table has no times, so those say only their day. The towns MassBuilds covers publish neither, and their pages say so. Each town has a page of its own (). The site's pages link to each other from its root (), as Pushpin's do, so (the entry in ) serves it as it's published. A project's address is its panel's, on whichever page it's opened: (an older link still opens it), which its name in any list links to and its panel's Copy link copies. Search engines are welcome: every page has a heading of its own (the header says the same in its own way), a description and a canonical address; a town's page says a few lines about its town; each page carries what it is in JSON-LD (the site, the page, a town's projects as a list, and Have your say's meetings as events, with when each starts and where to join); and lists them all. A link to a project (, which its panel's Copy link copies) shows the project's own rendering, name and description, and whoever opens it lands on its panel; a link to any other page shows (the house and the statuses' rings on the site's black, drawn by with the icons), with the page's own title and description as its words. Every page ends in a footer, as Pushpin's: its pages, each town ( opens that town's list on the home page) and the sources. The site's mark is Tabler Icons' "building-community" (MIT), beside its name in the header; the icons in , and the picture a link shows, are drawn from that same path by , which strokes it as Tabler does.

• Boston's projects come from the Planning Department's map of projects under Article 80 review (anything over about 20,000 square feet or 15 homes); Cambridge's from its quarterly development log (50,000 square feet or 10 homes). The towns around them (INNER_RING: Somerville, Brookline, Medford and the rest) come from MAPC's MassBuilds, which MAPC's staff and the towns' planners keep up, some towns far more often than others, so each of those lists says when its data was last updated, in amber after six months. MassBuilds' "planning" (filed, approved or not) shows as proposed, and its "stalled" flag as stalled. Only projects with homes are listed, and finished ones only from 2020 on (COMPLETE_SINCE).
• Each project's status is one of proposed, approved, under construction, complete or stalled. A project's date is the latest of its filing, its approval, the day a build first saw its status change (each build compares with the last one's projects.json) and the date on our own edit. The first build has nothing to compare with, so Cambridge's projects, which have no dates of their own, go undated until they change.
• To correct a project, note something about it or add one the cities don't list, add a block to housing/edits.txt (its top explains how) and push; the page rebuilds at once. An edit that can't be used is reported in the build's log and skipped.
• Each project's panel has a Suggest a correction button, which opens a pre-filled issue titled Note with the note's fields under it. housing-notes.yml applies the repo owner's straight to edits.txt (housing/notes.py), replies, closes it and redeploys; anyone else's is labelled correction and left for the owner to judge, the site saying nothing until they note it themselves.
• Changes to MassBuilds' projects can go back to MassBuilds too, where anyone with an account can propose an edit or flag a record for MAPC to review. python3 -m housing.upstream lists what our edits would change there, each with its MassBuilds page, and whether it can go as an edit (MassBuilds takes one only if it leaves the whole record valid) or needs a flag. With --send, and MASSBUILDS_EMAIL and MASSBUILDS_PASSWORD in the environment (never in the repo), it posts each: an edit or a flag, both of which a MassBuilds moderator sees before anything changes there. It's run by hand, never by a build, since it posts publicly under that account; housing/sent.txt keeps what's gone up, so nothing goes twice.

Visitor counts (GoatCounter)

Pushpin Boston's visits are counted with GoatCounter, free for a personal, non-commercial site. It uses no cookies and keeps nothing personal, so no cookie notice is needed; the About page's "Does it track me?" answer says so. Only Pushpin Boston is counted, not the newsfeed or the personal events page.

• Where: https://hagenah.goatcounter.com, signed in with the GoatCounter account. Each public page's head loads https://gc.zgo.at/count.js pointed at GOATCOUNTER in events/build.py (https://hagenah.goatcounter.com/count); to move to another GoatCounter site, change that.
• What's counted: a visit to each page by its own address (/boston/, /boston/film/, /boston/weekend/; a ?venue= or ?q= doesn't make another), with where it came from, country, and device. Switching to Music, Film or Art & talks on the home page counts as a visit to that page. And, as events, which appear in the same list marked as events:
  • open/<venue>: a listing's view opened.
  • listing/<venue>: a listing followed to its venue's page, from its view or straight from its name, with the event's name as its title. Which venues send people out.
  • venue/<venue>: a venue chosen from the menu.
  • share/<venue>: a listing shared (share/several theaters for a film at more than one).
• Leaving out your own visits: open https://pushpin.city/boston/#toggle-goatcounter once in each browser (Mac and phone). An alert says counting is now disabled there; opening it again turns it back on. It's kept in that browser's storage, so clearing the site's data undoes it.
• Checking it works: on the live site, the browser's Network tab shows a request to hagenah.goatcounter.com/count for each page (none in a browser that's toggled off). In the console, goatcounter.filter() gives false when it's counting, or the reason it isn't. It never counts localhost, so a local build isn't counted.
• More: GoatCounter's settings can make the dashboard public, and export everything as CSV. For how people find the site through Google, Search Console is worth adding too (verify pushpin.city with a TXT record at Hover, then submit https://pushpin.city/boston/sitemap.xml).

When a source fails

• Each build publishes what its page was built from, feeds.json and listings.json. When a source fails, or suddenly returns nothing while it had items coming up, the next build uses its items from there instead, if they're under two days old, and says so at the bottom of the page. A feed that's just quiet isn't a failure.
• A source that fails every build for six hours gets a "Source failing: ()" issue here, so GitHub emails about it. It closes itself once the source loads again.
• When a site changes and its reader is fixed, save a fresh sample of it in tests/fixtures too.

Publishing

deploy.yml runs the tests, then builds and publishes both pages:

• The newsfeed is this repo's GitHub Pages site.
• A repo can publish only one Pages site, so what's left at events.grahamhagenah.com (its listings and the page pointing on to Pushpin) is pushed to the gh-pages branch of grahamhagenah/events. The push uses a deploy key that can write to that repo only, kept as the EVENTS_DEPLOY_KEY secret here (its public half is under that repo's Settings → Deploy keys). Deploy keys don't expire.
• The housing tracker is pushed the same way, to grahamhagenah/housing, with the HOUSING_DEPLOY_KEY secret. Without that secret it's built but not published.
• The newsfeed rebuilds every run; the housing tracker every six hours; the events page every three hours, since listings change slowly and the theaters' sites are small. A push rebuilds both at once.

Scheduled builds

GitHub's own schedule trigger skips most runs, so a cron-job.org job named "Newsfeed build" starts the deploy every 15 minutes instead. Each run rebuilds the newsfeed; the events pages rebuild only when their last build is 3 hours old (EVENTS_EVERY_HOURS in deploy.yml, which a push, or a manual run with "events" ticked, skips). The schedule in deploy.yml stays as a backup.

• The job: POST https://api.github.com/repos/grahamhagenah/news/actions/workflows/deploy.yml/dispatches with body {"ref":"main"} and headers Authorization: Bearer <token>, Accept: application/vnd.github+json, X-GitHub-Api-Version: 2022-11-28, Content-Type: application/json, and User-Agent: cron-job.org. GitHub answers 204. Without the User-Agent header it answers 403.
• The token: a fine-grained token on the grahamhagenah account, limited to this repo with Actions: Read and write only. It can start and cancel builds but can't read or change code. It expires; renew it at github.com/settings/personal-access-tokens and paste the new one into the job's Authorization header.
• If the pages go stale: check cron-job.org's history or failure emails. A 401 means the token expired or was revoked, and a 403 means a missing permission or header.
• Keep-alive: GitHub disables a workflow after 60 days without a commit, which would also block the job. So on scheduled and dispatched runs, the keepalive job makes an empty commit if the repo has been quiet for 50 days.

Looking after it:

• Is it running? gh run list -R grahamhagenah/news --workflow deploy.yml --event workflow_dispatch -L 5 should show a run every 15 minutes, as should the Actions tab filtered by event. A cancelled one now and then is a run a push replaced. The newsfeed's "Updated" time in its header says when it last built.
• Renewing the token, before it expires (GitHub emails a week ahead; a calendar reminder helps too): at github.com/settings/personal-access-tokens, open the token cron-job.org uses and choose Regenerate token, which keeps its repo and permission. Copy it once, and in cron-job.org open the job, then Advanced → Headers, and replace the Authorization header with Bearer <new token>; save. The job's "Test run" should answer 204, and a new dispatched run should appear within a minute. Never paste the token anywhere else.
• Failure emails: in the job's settings, turn on notifications on failure, so an expired token (a 401) is noticed the same day rather than when the pages go stale.
• If GitHub disabled the workflow (after 60 quiet days, if the keep-alive ever missed): gh workflow enable deploy.yml -R grahamhagenah/news, or Actions → Build and deploy → Enable workflow.
• Without the job, the pages still rebuild from deploy.yml's own schedule, just less often: GitHub drops many of its scheduled runs.