POSSE to Mastodon

A Mastodon syndication script for articles and notes: state keyed by canonical URL, OG image uploads that fail open, backoff on 429, dry runs and batch limits.

Article Created Updated

Reviewed by adrian on

Once the Bluesky flow had settled, Mastodon was next. Same brief: no copying by hand, no duplicate posts on re-runs, and a large backfill should not fall over at the first rate limit. The result was its own script, its own state file and a deploy hook that mirrored the Bluesky setup piece for piece.

The setup

  • Site: an Astro 6 static build with RSS feeds per type (articles.xml, notes.xml).
  • Deploy: a shell script that builds, syncs to a VPS and then runs one syndication script per target.
  • Mastodon: the standard REST API with an app token. Media upload and status creation are two calls.

The script

scripts/mastodon-syndicate.mjs reads two feeds and posts every item that is not in the state yet:

const SOURCES = [
    { rssUrl: 'https://adrian-altner.de/rss/articles.xml', label: 'article' },
    { rssUrl: 'https://adrian-altner.de/rss/notes.xml', label: 'note' },
];

State keyed by canonical URL

The script runs on every deploy, so without state it would post everything every time. The state lives in .mastodon-posted.json, with the canonical content URL as key and the Mastodon status URL as value:

{
    "https://adrian-altner.de/articles/2026/03/24/.../": "https://mastodon.social/@altner/1162..."
}

That one structure does two jobs. Already posted URLs are skipped on the next run. And article and note pages show "Shared on Mastodon" by looking up their canonical URL in the file (the same idea as in Syndication Links from State).

Post text and media

Every post has the same shape:

Title

Teaser

Canonical URL

For the image the script fetches the og:image of each page, compresses it with sharp, uploads it to Mastodon's media API and passes media_ids[] when creating the status. If the media upload fails, the post goes out without an image instead of failing the whole run.

Deploy integration

The deploy script reads three variables and runs the script after the deploy:

MASTODON_BASE_URL=...
MASTODON_ACCESS_TOKEN=...
MASTODON_VISIBILITY=public

When .mastodon-posted.json changes, it is committed and pushed, exactly like .bluesky-posted.json. Otherwise the state resets on the next checkout and old items are posted again.

Hardening for the backfill

Two problems showed up almost at once. A large backfill hits the media upload rate limit and gets 429. And the first real run is the worst moment to find a bug. The script gained three things:

  • Retry with backoff for media uploads, honouring Retry-After when the server sends it.
  • MASTODON_DRY_RUN: simulate the run without calling any POST endpoint.
  • MASTODON_LIMIT: post at most N items in this run, for controlled batches.

On normal deploys none of this matters, since there is one new post and not 200.

Result

New articles and notes went to Mastodon on every deploy. The status URLs stayed in local state and appeared as u-syndication links on each post page. The site stayed the canonical source, and the Mastodon copies could be rebuilt from the feeds and the state.

Takeaways

  • A separate script and state file per target means no shared state and no shared failure.
  • Canonical URL as key and remote URL as value covers both deduplication and the u-syndication links.
  • Build the dry-run and limit flags before the first big backfill, not after it.

Based on

  • POSSE to Mastodon: State, Media Uploads, and Safer Deploys (raw/2026/2026-03-24/posse-to-mastodon-state-media-uploads-and-safer-deploys.md) [post]

More on this

Topic

  • IndieWeb Publishing on your own domain first and connecting personal websites with open standards such as Webmention and Microformats.

Basis for

  • Troubleshooting Mastodon Backfeed A runbook for Mastodon, Bridgy and webmention.io: token scopes, deploy order, trailing slashes, 429s on media uploads and reactions that are gone upstream.

Builds on

  • POSSE to Bluesky with the AT Protocol A Node script at the end of every deploy that posts new articles from the RSS feed to Bluesky as rich link cards, straight through the AT Protocol API.

Uses

  • Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.

Mentioned

  • Syndication Links from State Astro imports the syndication state file at build time and renders u-syndication links on every post, so the frontmatter never needs a second edit.

Show in the graph view