Automated Bluesky ATProto Backup using GitHub Actions

A Github Actions workflow that automatically backs up your ATProto (Bluesky) account data directly to a seperate branch in your repository.

Because this backup includes your account preferences, the fork of this repository should PRIVATE.

By default, this workflow runs every Sunday at midnight (UTC). It authenticates with your PDS and downloads:

• Your prefs.json (Account preferences, muted words, saved feeds, etc.)
• Your repository.car (Your entire post history and account graph in standard ATProto format)
• A blobs/ directory (All of your uploaded images, media, etc)

To prevent your repository from hitting GitHub's storage limits, it automatically prunes older backups. By default, it keeps the 6 most recent backups on an branch called backup-data.

Setup Instructions

1. Fork the repository

Fork this repository to your own GitHub account (make sure your fork is private).

2. Prepare your App Password

Create a dedicated App Password (do not use your main account password):

1. Log into Bluesky (via web or mobile app).
2. Go to Settings > App Passwords.
3. Click Add App Password.
4. Name it (e.g. Automatic Backup) and copy the generated password.

3. Set your repository variables

Go to your GitHub repository's Settings > Secrets and variables > Actions.

Under the "Secrets" tab, add:

• ATPROTO_APP_PASSWORD: Paste the app password you generated in Step 2.

Under the "Variables" tab, add:

• ATPROTO_HANDLE: Your full handle (e.g., user.bsky.social).

Optional Variables:

• ATPROTO_PDS_URL: If your account is on a non-bluesky PDS (selfhosted, blacksky, northsky, etc), set your specific server URL here. If you are on a deafult Bluesky PDS, don't set this variable (the script will default to the https://bsky.social PDS entryway).
• RETENTION_COUNT: The number of backups to keep before older ones are deleted. Defaults to 6 if left blank.

4. Run Your First Backup

The backup will run automatically every Sunday, but you can trigger it right now to make sure everything works:

1. Go to the Actions tab in your repository.
2. Click on the Automated ATProto Backup workflow on the left.
3. Click the Run workflow dropdown on the right and start it.

Once the workflow finishes successfully, it will create a new branch in your repository called backup-data that stores your timestamped backups.