- Python 97.5%
- Shell 2.2%
- Dockerfile 0.3%
| tests | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| autopost.py | ||
| config.example.yaml | ||
| docker-compose.yml | ||
| Dockerfile | ||
| get_gts_token.sh | ||
| pytest.ini | ||
| README.md | ||
| requirements-dev.txt | ||
| requirements.txt | ||
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:
- Post the most recent article from your feed (for testing/verification)
- Mark all current posts as "seen" to avoid spam
- 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
Using Docker (Recommended)
- Clone this repository:
git clone <your-repo-url>
cd autopost
- Create the config directory:
mkdir -p config data
- Copy and edit the configuration:
cp config.example.yaml config/config.yaml
nano config/config.yaml
- Build and run with Docker Compose:
docker-compose up -d
- Check logs:
docker-compose logs -f
Using Python Directly
- Install dependencies:
pip install -r requirements.txt
- Copy and edit the configuration:
cp config.example.yaml config.yaml
nano config.yaml
- 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:
- Go to your Mastodon instance Settings → Development → New Application
- Give it a name (e.g., "Autopost")
- Required scopes:
write:statusesandwrite:media - 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:
- Ask for your GoToSocial instance URL
- Create an OAuth application
- Open your browser to authorize the app
- Prompt you to paste the authorization code
- Exchange the code for an access token
- 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:
- 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"
}'
- 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
-
Get the authorization code after clicking "Authorize"
-
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
- Feed Monitoring: Periodically checks configured RSS/Atom feeds, using
ETag/If-Modified-Sinceso an unchanged feed costs almost nothing - Post Detection: Identifies new posts not yet shared
- Content Extraction: Extracts title, link, tags, and featured image
- Formatting: Creates social media post using your template
- Publishing: Posts to Mastodon/GoToSocial with image attachment, using an idempotency key so a retried request cannot create a duplicate
- 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
--debugflag for more detailed output
Images aren't uploading
- Ensure
download_images: truein 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=XXXXXparameter - 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) andinitialized_feeds(feed URLs that have been seen) - If duplicates appear anyway, the most likely cause is your post URLs changing.
Run with
--debugand look forAlready 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.
- Try the backup:
cp data/posted_items.json.bak data/posted_items.json - 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:
- Stop the application
- Edit the state file (
data/posted_items.jsonorposted_items.json) - Remove every key for that post from
posted_keys— there is normally one each ofurl:,slug:andtitle:. Leaving any of them behind means the post is still considered shared - 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"):
- Stop the application
- Edit the state file (
data/posted_items.jsonorposted_items.json) - Remove the feed URL from the
initialized_feedsarray - Optionally remove associated keys from
posted_keysif you want them reposted - 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_minutesto 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_dirmust point at your Hugocontent/directory, and it must be mounted into the container (seedocker-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!