Publish an RSS or Atom feed to Bluesky

Preview new feed entries before posting. This tutorial gives you a reusable RSS/Atom importer and a local queue, with explicit publication and recovery steps.

By The Bluesky.bot team

Published:
Updated:
Reviewed:

What this tutorial builds

Turn new articles from an RSS 2.0 or Atom 1.0 feed into a small, controlled queue of Bluesky posts. Start with a preview, remember the feed's existing archive without posting it, then explicitly enable publication. This is RSS → Bluesky, not a custom Bluesky feed and not a way to read a Bluesky account in an RSS reader.

You need Python 3.11 or later, a local persistent disk, a feed you own or have permission to redistribute, and a bot account you control. The sample supports plain text and one article link. Images, replies, mentions, relative feed URLs and HTML-rich titles need a separate implementation. Bluesky.bot supplies the guide and download; you run the bot on your own machine.

1. Download and test the reusable kit

Download the MIT-licensed posting recipes. Extract the archive in a new directory. The package includes the queue, RSS importer, RSS/Atom fixtures and offline tests; it contains no credentials or enabled workflow.

bash
tar -xzf bluesky-bot-recipes.tar.gz
cd bluesky-bot-recipes
python3 -m unittest -v test_recipes.py

The tests simulate publication and recovery. They do not prove that an authenticated post succeeded on your account. You can use the preview without installing the Bluesky SDK.

2. Try an initial baseline without posting old articles

Initialize the sample RSS feed, then preview the sample Atom document with a new entry:

bash
python3 rss_to_queue.py sample-rss.xml --feed-id my-blog --db .state/rss.sqlite3 --baseline
python3 rss_to_queue.py sample-atom.xml --feed-id my-blog --db .state/rss.sqlite3

The first command remembers the two RSS identities and creates no posts. The second previews one new Atom item, choosing its article link rather than its audio enclosure. A GUID or Atom ID is an opaque identity: it is not necessarily a URL.

For your real feed, download its current XML into feed.xml and run the baseline once with a separate database. Use your own feed's stable name as --feed-id. Do not repeat a baseline on every poll: that would hide newly arrived entries.

bash
curl --fail --location --max-time 20 --max-filesize 5242880 "https://example.org/feed.xml" --output feed.xml
python3 rss_to_queue.py feed.xml --feed-id my-blog --db .state/live.sqlite3 --baseline

Replace the example address with your actual feed. The importer reads local XML, not credentials or a remote account. Keep downloads bounded, and only fetch a feed you trust.

3. Preview new items, then enqueue them explicitly

After the feed changes, download it again and inspect the preview:

bash
python3 rss_to_queue.py feed.xml --feed-id my-blog --db .state/live.sqlite3
python3 rss_to_queue.py feed.xml --feed-id my-blog --db .state/live.sqlite3 --enqueue
python3 posting_queue.py --db .state/live.sqlite3 run

--enqueue writes a local pending job and remembers the feed identity in the same transaction. It still does not sign in or post. Re-importing the same item keeps one job. The queue's default run command previews due text without changing its delivery status.

Start with one item per run. --limit 5 is the maximum batch, not a recommended publishing frequency. For a typical newest-first feed the importer starts at the oldest unseen entry still present; it does not infer a complete chronological history. Poll often enough that articles do not disappear from the feed between reads.

Entries without an absolute HTTP(S) article link or title, or with text over the conservative 300-code-point cap, are skipped with a diagnostic. Shorten them deliberately rather than cutting a URL. The feed parser accepts at most 5 MiB and rejects DTD/entities and NUL bytes. It does not fetch full articles or generate images.

Feed dates (pubDate, published and updated) are not scheduling instructions in this kit. New eligible entries are queued at observation time. For an embargo or a future publication time, prepare an explicitly dated job in the scheduling tutorial instead.

4. Connect your own bot and publish one checked item

Follow the app-password setup and revocation guide. Use a dedicated app password for this bot, never the account's main password. For a service connecting other people's accounts, implement OAuth instead.

bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

Set BLUESKY_HANDLE and BLUESKY_APP_PASSWORD in your local environment or a protected local environment file. Use the correct HTTPS PDS in BLUESKY_SERVICE if the account is not hosted on bsky.social. Keep secrets out of the feed, JSON queue, Git, screenshots and terminal history.

bash
python3 posting_queue.py --db .state/live.sqlite3 run --publish
python3 posting_queue.py --db .state/live.sqlite3 status

--publish is the explicit switch that opens a session and writes a due post. A confirmed response is recorded as sent with its at:// URI. Check the post and clickable article link in Bluesky before putting the command on a timer. The database is bound to that bot's DID; use one database per bot.

5. Keep state and review uncertain writes

Use the complete scheduling tutorial for persistent storage, cron, timezones, cancellation and restart behavior. A fresh CI workspace cannot remember an earlier run merely because the same script is present.

The queue commits publishing before the network call. Another worker does not claim that job. A failed or lost response becomes review; a crash can leave publishing. These states stop automatic replay because a timeout may have happened after the server accepted the post. Each job retains its reserved record key for an explicit retry.

bash
python3 posting_queue.py --db .state/live.sqlite3 status
python3 posting_queue.py --db .state/live.sqlite3 cancel JOB_ID

Only a pending job can be cancelled. For review or publishing, stop the worker and inspect the bot's public record at the key shown by status, using the repository explorer. Confirm the actual content before resolving it. If you cannot establish the outcome, leave the job for review. The README documents the explicit resolution commands; the kit does not guarantee exactly-once delivery after a lost database.

Troubleshooting and a useful launch checklist

  • No jobs: check that you initialized only once, kept the same feed ID/database, downloaded a changed document, and used the expected article links.
  • Repeated article: inspect whether the publisher changes its GUID on every edit. Stable identities are required; changing IDs or deleting the database defeats duplicate tracking.
  • An article is missing: check skipped-item diagnostics and whether it had already left the feed before polling. A feed is not a complete archive.
  • Authentication failure: verify the bot account, current app password and actual PDS. See the Python first-post tutorial for the SDK basics.
  • Rate limit or uncertain outcome: stop, inspect status, follow the server's retry guidance and review any outstanding write before resuming. Do not loop over login or generate new IDs to force a retry.

Before unattended use: baseline archives, preview a new article, publish one deliberate test, verify the link, back up state, simulate a restart and confirm how to cancel. Identify the account as automated and follow the automation best practices. Your feed should link back to its original authors; having an RSS URL is not blanket permission to copy full articles.

The kit is reusable under MIT, including its fixtures and offline tests. You can share the tutorial or adapt the examples without a mandatory backlink. Citation and reuse are welcome; publishing a resource does not guarantee links, search placement or traffic.

Sources