Watches blog feeds and posts new articles to Mastodon or GoToSocial.
  • Python 97.5%
  • Shell 2.2%
  • Dockerfile 0.3%
Find a file
2026-11-13 04:01:49 -05:00
tests Reap Git processes and enable container init 2026-11-13 04:01:49 -05:00
.dockerignore Add test suite 2026-09-02 02:23:10 -04:00
.env.example Take compose paths from .env, and make ssh work as a non-root uid 2026-10-09 14:23:27 -04:00
.gitignore Initial commit 2025-11-12 02:21:29 -05:00
autopost.py Reap Git processes and enable container init 2026-11-13 04:01:49 -05:00
config.example.yaml Take compose paths from .env, and make ssh work as a non-root uid 2026-10-09 14:23:27 -04:00
docker-compose.yml Reap Git processes and enable container init 2026-11-13 04:01:49 -05:00
Dockerfile Commit and push frontmatter updates back to the blog repo 2026-10-09 14:03:27 -04:00
get_gts_token.sh fixes 2025-11-12 03:01:10 -05:00
pytest.ini Add test suite 2026-09-02 02:23:10 -04:00
README.md Reap Git processes and enable container init 2026-11-13 04:01:49 -05:00
requirements-dev.txt Add test suite 2026-09-02 02:23:10 -04:00
requirements.txt Fix duplicate posts, dead frontmatter updater, and state loss 2026-09-02 02:03:30 -04:00

Autopost

Automatically post blog updates from multiple Hugo (or any RSS/Atom feed) blogs to Mastodon or GoToSocial. Converts blog post tags to hashtags and includes featured images.

Features

  • Monitor multiple blog RSS/Atom feeds
  • Support for both Mastodon and GoToSocial
  • Automatically converts Hugo tags to hashtags
  • Downloads and attaches featured images
  • Tracks posted items to avoid duplicates
  • Configurable post templates
  • Docker support for easy deployment
  • Scheduled checks or one-time runs
  • Smart first-run: Won't spam your existing posts - only shares NEW posts

Important: First Run Behavior

When you first run the app or add a new blog to your configuration, it will:

  1. Post the most recent article from your feed (for testing/verification)
  2. Mark all current posts as "seen" to avoid spam
  3. Only post NEW posts that are published after initialization

This prevents flooding your social media with old posts when you first set up the app or add a new blog, while still giving you immediate feedback that the posting works.

Quick Start

  1. Clone this repository:
git clone <your-repo-url>
cd autopost
  1. Create the config directory:
mkdir -p config data
  1. Copy and edit the configuration:
cp config.example.yaml config/config.yaml
nano config/config.yaml
  1. Build and run with Docker Compose:
docker-compose up -d
  1. Check logs:
docker-compose logs -f

Using Python Directly

  1. Install dependencies:
pip install -r requirements.txt
  1. Copy and edit the configuration:
cp config.example.yaml config.yaml
nano config.yaml
  1. Run the application:
# Run continuously (checks periodically)
python autopost.py

# Run once and exit
python autopost.py --once

# Enable debug logging
python autopost.py --debug

Configuration

Getting Access Tokens

For Mastodon:

  1. Go to your Mastodon instance Settings → Development → New Application
  2. Give it a name (e.g., "Autopost")
  3. Required scopes: write:statuses and write:media
  4. Copy the access token

For GoToSocial:

Easy Method (Recommended): Use the included script

We provide a helper script that automates the entire OAuth flow:

./get_gts_token.sh

The script will:

  1. Ask for your GoToSocial instance URL
  2. Create an OAuth application
  3. Open your browser to authorize the app
  4. Prompt you to paste the authorization code
  5. Exchange the code for an access token
  6. Display the token and ready-to-use config snippet

What to look for after clicking "Authorize":

  • The authorization code might be displayed on the page
  • Check the URL bar for ?code=XXXXX
  • Try View Page Source (right-click) and search for "code"
  • Copy the code and paste it into the terminal

Manual Method:

If you prefer to do it manually or the script doesn't work:

  1. Create an OAuth app:
curl -X POST https://your-gts-instance.com/api/v1/apps \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Autopost",
    "redirect_uris": "urn:ietf:wg:oauth:2.0:oob",
    "scopes": "write:statuses write:media"
  }'
  1. Visit the authorization URL in your browser (replace CLIENT_ID):
https://your-gts-instance.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=write:statuses+write:media
  1. Get the authorization code after clicking "Authorize"

  2. Exchange for access token:

curl -X POST https://your-gts-instance.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
    "grant_type": "authorization_code",
    "code": "AUTH_CODE"
  }'

Note: The name field in your config can be anything you want - it's just an internal label to connect blogs to accounts. Just make sure it matches between social_accounts[].name and blogs[].social_account.

Configuration File

Edit config.yaml (or config/config.yaml for Docker):

social_accounts:
  - name: "my-mastodon"
    type: "mastodon"
    instance_url: "https://mastodon.social"
    access_token: "YOUR_TOKEN_HERE"

blogs:
  - name: "My Blog"
    # Prefer a section feed. A site root index.xml usually also carries pages
    # (/about/, /now/) and other sections, which would be posted as articles.
    feed_url: "https://yourblog.com/posts/index.xml"
    social_account: "my-mastodon"
    post_template: |
      {title}

      {tags}

      {link}
    enabled: true

settings:
  check_interval_minutes: 15
  state_file: "/app/data/posted_items.json"  # For Docker - MUST be absolute
  # state_file: "posted_items.json"  # For local
  max_hashtags: 10
  download_images: true
  max_posts_per_run: 5
  dedupe_keys: ["url", "slug", "title"]

See config.example.yaml for every available setting with comments.

Post Template Variables

  • {title} - Blog post title
  • {link} - URL to the blog post
  • {tags} - Hashtags generated from blog tags

Any other {placeholder} is a config error and is reported at startup. To include a literal brace, double it: {{ or }}.

Testing Your Configuration

python autopost.py --config config.yaml --validate

Checks the config and exits. Catches missing fields, bad templates, unknown account references, invalid regexes, and a relative state_file in Docker.

python autopost.py --config config.yaml --dry-run

Fetches your feeds and prints exactly what would be posted, without posting, without writing the state file, and without touching your Hugo content. Run this first.

How It Works

  1. Feed Monitoring: Periodically checks configured RSS/Atom feeds, using ETag/If-Modified-Since so an unchanged feed costs almost nothing
  2. Post Detection: Identifies new posts not yet shared
  3. Content Extraction: Extracts title, link, tags, and featured image
  4. Formatting: Creates social media post using your template
  5. Publishing: Posts to Mastodon/GoToSocial with image attachment, using an idempotency key so a retried request cannot create a duplicate
  6. State Tracking: Records posted items to prevent duplicates

How Duplicates Are Prevented

A permalink is not a stable identifier for a post. In Hugo, moving a file from content/posts/2026/drafts/foo.md to content/posts/2026/music/foo.md changes the URL, which changes the feed's <guid> — and an article you already shared starts looking brand new.

Each post is therefore recorded under several keys, and matching any one of them counts as "already shared":

Key Value Survives
url the permalink nothing — exact match only
slug the last URL path segment moving the file between folders
title the slugified title changing the slug

Configure with dedupe_keys. Drop title if you legitimately reuse post titles; drop slug if the same slug appears in more than one section.

On top of that, max_posts_per_run (default 5) caps how many posts can go out in a single cycle, so anything that makes a lot of old posts look new is capped at a handful of toots rather than your entire archive.

Docker Usage

Compose uses init: true to reap orphaned Git/SSH helpers. Recreate the container after updating an older deployment; a restart alone does not enable the init process. If you launch the image with docker run, include --init.

Build the image:

docker-compose build

Run in background:

docker-compose up -d

Run once for testing:

docker-compose run --rm autopost python autopost.py --config /app/config/config.yaml --once

View logs:

docker-compose logs -f autopost

Stop the service:

docker-compose down

File Structure

autopost/
├── autopost.py           # Main application
├── requirements.txt      # Python dependencies
├── config.example.yaml   # Example configuration
├── get_gts_token.sh     # Helper script to get GoToSocial tokens
├── Dockerfile           # Docker image definition
├── docker-compose.yml   # Docker Compose configuration
├── config/              # Configuration directory (for Docker)
│   └── config.yaml     # Your actual configuration
└── data/               # Data directory (for Docker)
    └── posted_items.json  # State tracking file

Troubleshooting

Posts aren't being detected

  • Check that your feed URL is correct and accessible
  • Verify the feed is valid RSS/Atom format
  • Check logs for parsing errors: docker-compose logs -f
  • Try running with --debug flag for more detailed output

Images aren't uploading

  • Ensure download_images: true in settings
  • Check that your blog's RSS feed includes image information
  • Verify the image URLs are publicly accessible
  • Check Mastodon/GoToSocial file size limits

Authentication errors

  • Verify your access token is correct
  • Check that the instance URL is correct (include https://)
  • Ensure the access token has required permissions (write:statuses, write:media)
  • For GoToSocial, verify API compatibility

GoToSocial authorization code not appearing

If you click "Authorize" and nothing happens when getting a token:

  • Check the page source: Right-click → View Page Source, search for "code"
  • Check the URL bar: Look for ?code=XXXXX parameter
  • Check browser console: Press F12, look for errors or displayed codes
  • Try a different browser: Some browsers handle the OAuth flow differently
  • The authorization code might be displayed as plain text on the page itself

The code will look like a long string of random characters (e.g., MZBKNWU4NMITYMYZMY0ZODGZLWIZMDKTMMFKNTG0MJEYZDK2)

Duplicate posts

  • The state file is written atomically and keeps the previous version as posted_items.json.bak
  • It contains posted_keys (see How Duplicates Are Prevented) and initialized_feeds (feed URLs that have been seen)
  • If duplicates appear anyway, the most likely cause is your post URLs changing. Run with --debug and look for Already posted (slug:...) lines to see which key matched

If a state file from an older version is present it is migrated automatically: each stored permalink becomes a url: key plus a derived slug: key.

"State file exists but could not be parsed"

The app refuses to start rather than continue with empty state, because empty state means every feed looks new and your whole archive gets re-posted.

  1. Try the backup: cp data/posted_items.json.bak data/posted_items.json
  2. If there is no usable backup, delete data/posted_items.json. The next run re-initialises: it posts only the most recent article and marks the rest seen

I want to post an old article manually

If you want to share a specific old post that was already in your feed when you initialized:

  1. Stop the application
  2. Edit the state file (data/posted_items.json or posted_items.json)
  3. Remove every key for that post from posted_keys — there is normally one each of url:, slug: and title:. Leaving any of them behind means the post is still considered shared
  4. Restart the application - it will post that article on the next check

Resetting a blog feed (advanced)

If you want to reinitialize a blog feed (e.g., for testing or to change which posts are considered "old"):

  1. Stop the application
  2. Edit the state file (data/posted_items.json or posted_items.json)
  3. Remove the feed URL from the initialized_feeds array
  4. Optionally remove associated keys from posted_keys if you want them reposted
  5. Restart - the feed will be reinitialized (posting the most recent article and marking all as seen)

Rate limiting

  • The app includes a 5-second delay between posts (post_delay_seconds)
  • Network errors, rate limits and 5xx responses are retried with exponential backoff. Posts carry an idempotency key, so a retry cannot produce a duplicate
  • Adjust check_interval_minutes to reduce frequency
  • Consider the rate limits of your instance

Committing the status ID back to your blog repo

If autopost runs somewhere other than your Hugo working copy — a homelab, while the site is built by CI from a git remote — then writing fediverse.id to a local file isn't enough on its own. The ID has to be committed and pushed before the built site can see it.

Give the machine running autopost its own clone, used for nothing else, and enable hugo_git:

blogs:
  - name: "My Blog"
    hugo_content_dir: "/app/hugo/content"
    hugo_git:
      enabled: true
      remote: "origin"
      branch: "main"
      ssh_key: "/app/ssh/id_ed25519"
      author_name: "autopost"
      author_email: "autopost@example.com"
      commit_message: "Add fediverse ID for {title}"

Mount the clone and a deploy key in docker-compose.yml:

    volumes:
      - /srv/autopost/mtwb:/app/hugo          # the repo ROOT, not content/
      - /srv/autopost/ssh:/app/ssh:ro

Mount the repository root, not content/. .git lives one level above content/, so bind-mounting just the content directory leaves it outside the container and nothing can be committed. --validate checks for this.

Each commit touches exactly one file, so each one triggers one CI build. Pushing happens once per cycle, not once per post.

What it will not do: stage anything beyond the single file it just changed, force-push, or resolve a conflict. If a rebase onto the remote doesn't apply cleanly it aborts, leaves the commit local, and retries next cycle — so a conflict delays the comment section rather than losing or overwriting anything. Unrelated edits sitting dirty in that clone are left untouched.

ssh_key uses StrictHostKeyChecking=accept-new, which pins the host key on first connection. Mount a known_hosts file if you'd rather pin it yourself.

Frontmatter isn't being updated

  • hugo_content_dir must point at your Hugo content/ directory, and it must be mounted into the container (see docker-compose.yml)
  • Run with --debug; the log shows whether each URL resolved by path match or slug match, or not at all
  • Ambiguous slugs (the same file name in two sections) are skipped with a warning rather than guessed at

Development

Checking a change:

# Validate the config only
python autopost.py --config config.yaml --validate

# Show what would be posted, without posting anything
python autopost.py --config config.yaml --dry-run

# Run one real cycle with full logging
python autopost.py --once --debug

Running the tests

pip install -r requirements-dev.txt && pytest

No network, no instance, no config needed — the suite builds its own Hugo tree and feeds. If you don't have Python locally, run it in the container:

docker run --rm -v "$PWD:/src:ro" python:3.11-slim sh -c "mkdir -p /work && cp -r /src/. /work && cd /work && pip install -q -r requirements-dev.txt && python -m pytest"

There is also an opt-in set that runs against a real feed and a real Hugo tree. This is worth running after any change to slug handling or file lookup, because it checks that every post in your feed still resolves to its source file — the failure that the synthetic fixtures were originally written to match:

AUTOPOST_LIVE_FEED=https://yourblog.com/posts/index.xml AUTOPOST_LIVE_CONTENT=/path/to/hugo/content pytest -m live

It also warns about identity-key collisions (two posts sharing a slug or title, where one would never be shared) and about feeds that carry non-article entries.

Modify check interval:

Edit check_interval_minutes in config.yaml

Custom post templates:

Customize the post_template for each blog in your config

License

MIT License - feel free to use and modify as needed

Contributing

Issues and pull requests welcome!