{"id":13467735,"url":"https://github.com/robertoszek/pleroma-bot","last_synced_at":"2025-10-08T11:10:10.489Z","repository":{"id":38376375,"uuid":"289859971","full_name":"robertoszek/pleroma-bot","owner":"robertoszek","description":"Bot for mirroring one or multiple Twitter accounts in Pleroma/Mastodon/Misskey.","archived":false,"fork":false,"pushed_at":"2023-10-29T23:46:10.000Z","size":18902,"stargazers_count":108,"open_issues_count":23,"forks_count":19,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-09-27T01:03:31.436Z","etag":null,"topics":["bot","fediverse-account","mastodon","mastodon-bot","misskey","misskey-bot","pleroma","pleroma-bot","python","tweets","twitter","twitter-api","twitter-bot"],"latest_commit_sha":null,"homepage":"https://robertoszek.github.io/pleroma-bot","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robertoszek.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":"robertoszek","patreon":"robertoszek","open_collective":null,"ko_fi":"robertoszek","tidelift":null,"community_bridge":null,"liberapay":"robertoszek","issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["paypal.me/robertoszek"]}},"created_at":"2020-08-24T07:37:01.000Z","updated_at":"2025-09-12T04:32:41.000Z","dependencies_parsed_at":"2023-02-15T13:00:51.699Z","dependency_job_id":"65373dbe-e9d7-4e99-8382-d131c213e2b5","html_url":"https://github.com/robertoszek/pleroma-bot","commit_stats":{"total_commits":519,"total_committers":7,"mean_commits":74.14285714285714,"dds":"0.21194605009633916","last_synced_commit":"9a64891385d8321a84c37f3fba1fba6bd7b785ee"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/robertoszek/pleroma-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertoszek%2Fpleroma-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertoszek%2Fpleroma-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertoszek%2Fpleroma-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertoszek%2Fpleroma-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robertoszek","download_url":"https://codeload.github.com/robertoszek/pleroma-bot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertoszek%2Fpleroma-bot/sbom","scorecard":{"id":780426,"data":{"date":"2025-08-11","repo":{"name":"github.com/robertoszek/pleroma-bot","commit":"9a64891385d8321a84c37f3fba1fba6bd7b785ee"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.8,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":0,"reason":"Found 0/1 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Info: FSF or OSI recognized license: MIT License: LICENSE.md:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":5,"reason":"5 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2021-142 / GHSA-8q59-q68h-6hv4","Warn: Project is vulnerable to: GHSA-9hjg-9r4m-mvj7","Warn: Project is vulnerable to: GHSA-9wx4-h78v-vm56","Warn: Project is vulnerable to: PYSEC-2023-74 / GHSA-j8r2-6x86-q33q","Warn: Project is vulnerable to: GHSA-g7vv-2v7x-gj9p"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-23T04:46:38.521Z","repository_id":38376375,"created_at":"2025-08-23T04:46:38.522Z","updated_at":"2025-08-23T04:46:38.522Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277787344,"owners_count":25876985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-01T02:00:09.286Z","response_time":88,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","fediverse-account","mastodon","mastodon-bot","misskey","misskey-bot","pleroma","pleroma-bot","python","tweets","twitter","twitter-api","twitter-bot"],"created_at":"2024-07-31T15:00:59.881Z","updated_at":"2025-10-08T11:10:10.473Z","avatar_url":"https://github.com/robertoszek.png","language":"Python","funding_links":["https://github.com/sponsors/robertoszek","https://patreon.com/robertoszek","https://ko-fi.com/robertoszek","https://liberapay.com/robertoszek","paypal.me/robertoszek"],"categories":["Python","bot"],"sub_categories":[],"readme":"# Stork (pleroma-bot)\n\n[![Build Status](https://travis-ci.com/robertoszek/pleroma-bot.svg?branch=develop)](https://app.travis-ci.com/github/robertoszek/pleroma-bot)\n[![Version](https://img.shields.io/pypi/v/pleroma-bot.svg)](https://pypi.org/project/pleroma-bot/)\n[![AUR version](https://img.shields.io/aur/version/python-pleroma-bot)](https://aur.archlinux.org/packages/python-pleroma-bot)\n[![codecov](https://codecov.io/gh/robertoszek/pleroma-bot/branch/master/graph/badge.svg?token=0c4Gzv4HjC)](https://codecov.io/gh/robertoszek/pleroma-bot)\n[![Python 3.6](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/release/python-360/)\n[![License](https://img.shields.io/github/license/robertoszek/pleroma-bot)](https://github.com/robertoszek/pleroma-bot/blob/master/LICENSE.md)\n\n![Stork](img/stork-smaller.svg)\n\nMirror your favorite Twitter accounts in the Fediverse, so you can follow their updates from the comfort of your favorite instance. Or migrate your own to the Fediverse using a Twitter [archive](https://twitter.com/settings/your_twitter_data).\n\n[![Documentation](img/docs.png)](https://robertoszek.github.io/pleroma-bot)\n\nYou can find this project at: \n\n|                          GitHub                           |                          Gitlab                           |                                Gitea                                 |\n|:---------------------------------------------------------:|:---------------------------------------------------------:|:--------------------------------------------------------------------:|\n| [pleroma-bot](https://github.com/robertoszek/pleroma-bot) | [pleroma-bot](https://gitlab.com/robertoszek/pleroma-bot) | [pleroma-bot](https://gitea.robertoszek.xyz/robertoszek/pleroma-bot) |\n\nSupports:\n\n|                          Mastodon                           |                         Pleroma                         |                         Misskey                          |\n|:-----------------------------------------------------------:|:-------------------------------------------------------:|:--------------------------------------------------------:|\n| [![Mastodon](/img/mastodon.png)](https://joinmastodon.org/) | [![Pleroma](/img/pleroma.png)](https://pleroma.social/) | [![Misskey](/img/misskey.png)](https://misskey-hub.net/) |\n\n## Introduction\n\nAfter using the pretty cool [mastodon-bot](https://github.com/yogthos/mastodon-bot) for a while, I found it was lacking some features which were of use to me. \n\nFor precisely those cases I've written this Python project that automates them, asking such info to [Twitter's API](https://developer.twitter.com/en/docs/twitter-api/v1) and updating the relevant fields on the [Pleroma API](https://api.pleroma.social/)/[Mastodon API](https://docs.joinmastodon.org/client/intro/)/[Misskey API](https://misskey-hub.net/en/docs/api) side.\n\n\n## Features \n\nSo basically, it does the following:\n* Can parse a Twitter [archive](https://twitter.com/settings/your_twitter_data), moving all your tweets to the Fediverse\n* Can use an RSS feed as the source of the tweets to post\n* Retrieves latest **tweets** and posts them on the Fediverse account if their timestamp is newer than the last post.\n  * Can filter out RTs or not\n  * Can filter out replies or not\n  * Supports Twitter threads\n* Media retrieval and upload of multiple **attachments**. This includes:\n  * Video\n  * Images\n  * Animated GIFs \n  * Polls\n* Retrieves **profile info** from Twitter and updates it in on the Fediverse account. This includes:\n  * *Display name*\n  * *Profile picture*\n  * *Banner image*\n  * *Bio text*\n* Adds some **metadata fields** to the Fediverse account, pointing to the original Twitter account or custom text.\n\n## Installation\n### Using pip\n```\n$ pip install pleroma-bot\n```\n### Using a package manager\nHere's a list of the available packages.\n\n| Package type   | Link                                                    | Maintainer                                    |\n|:--------------:|:-------------------------------------------------------:|:---------------------------------------------:|\n| AUR (Arch)     | https://aur.archlinux.org/packages/python-pleroma-bot  | [robertoszek](https://github.com/robertoszek) |\n\n## Usage\n```console\n$ pleroma-bot [-c CONFIG] [-l LOG] [--noProfile] [--daemon] [--forceDate [FORCEDATE]] [-a ARCHIVE]\n```\n\n```console\nBot for mirroring one or multiple Twitter accounts in Pleroma/Mastodon.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -c CONFIG, --config CONFIG\n                        path of config file (config.yml) to use and parse. If\n                        not specified, it will try to find it in the current\n                        working directory.\n  -d, --daemon          run in daemon mode. By default it will re-run every\n                        60min. You can control this with --pollrate\n  -p POLLRATE, --pollrate POLLRATE\n                        only applies to daemon mode. How often to run the\n                        program in the background (in minutes). By default is\n                        60min.\n  -l LOG, --log LOG     path of log file (error.log) to create. If not\n                        specified, it will try to store it at your config file\n                        path\n  -n, --noProfile       skips Fediverse profile update (no background image,\n                        profile image, bio text, etc.)\n  --forceDate [FORCEDATE]\n                        forces the tweet retrieval to start from a specific\n                        date. The twitter_username value (FORCEDATE) can be\n                        supplied to only force it for that particular user in\n                        the config\n  -s, --skipChecks      skips first run checks\n  -a ARCHIVE, --archive ARCHIVE\n                        path of the Twitter archive file (zip) to use for\n                        posting tweets.\n  -t THREADS, --threads THREADS\n                        number of threads to use when processing tweets\n  -L LOCKFILE, --lockfile LOCKFILE\n                        path of lock file (pleroma-bot.lock) to prevent\n                        collisions with multiple bot instances. By default it\n                        will be placed next to your config file.\n  --verbose, -v\n  --version             show program's version number and exit\n```\n### Before running\n\nThere are multiple options for using the bot.\n\nYou can either choose to use: \n\n- A Twitter archive\n- An RSS feed\n- Guest tokens\n- [Twitter tokens](https://developer.twitter.com/en/docs/authentication/api-reference/token) with a Developer account \n\nYou'll need to create a configuration file and obtain the [Fediverse tokens](https://tinysubversions.com/notes/mastodon-bot/) for your accounts no matter what you choose to use.\n\nIf you plan on retrieving tweets from an account which has their tweets **protected**, you'll also need the following:\n* Consumer Key and Secret. You'll find them on your project app keys and tokens section at [Twitter's Developer Portal](https://developer.twitter.com/en/portal/dashboard)\n* Access Token Key and Secret.  You'll also find them on your project app keys and tokens section at [Twitter's Developer Portal](https://developer.twitter.com/en/portal/dashboard). \nAlternatively, you can obtain the Access Token and Secret by running [this](https://github.com/joestump/python-oauth2/wiki/Twitter-Three-legged-OAuth-Python-3.0) locally, while being logged in with a Twitter account which follows or is the owner of the protected account\n\nYou'll may also need Elevated access in your Twitter's API project in order for the bot to function properly.\n\nRefer to the docs [for more info about this](https://robertoszek.github.io/pleroma-bot/gettingstarted/beforerunning/#before-running).\n\n### Configuration\n\nCreate a ```config.yml``` file in the same path where you are calling ```pleroma-bot``` (or use the `--config` argument to specify a different path). \n\nThere's a config example in this repo called ```config.yml.sample``` that can help you when filling yours out.\n\nFor more information you can refer to the [\"Configuration\" page](https://robertoszek.github.io/pleroma-bot/gettingstarted/configuration/) on the docs.\n\nHere's what a minimal config looks like:\n```yaml\n# Change this to your target Fediverse instance\npleroma_base_url: https://pleroma.instance\n# How many tweets to gather per-user in every execution\n# Twitter's API hard limit is 3,200\nmax_tweets: 40\n# Twitter bearer token\ntwitter_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\nusers:\n- twitter_username: User1\n  pleroma_username: MyPleromaUser1\n  # Mastodon/Pleroma bearer token\n  pleroma_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n```\n\n### Running\n\nIf you're running the bot for the first time it will ask you for the date you wish to start retrieving tweets from (it will gather all from that date up to the present). \nIf you leave it empty and just press enter it will default to the oldest date that Twitter's API allows ('```2010-11-06T00:00:00Z```') for tweet retrieval.\n\nTo force this behaviour in future runs you can use the ```--forceDate``` argument (be careful, no validation is performed with the already posted toots/posts by that Fediverse account and you can end up with duplicates posts/toots!).\n\nAdditionally, you can provide a ```twitter_username``` if you only want to force the date for one user in your config.\n\nFor example:\n\n```console\n$ pleroma-bot --forceDate WoolieWoolz\n```\n\nIf the `--noProfile` argument is passed, the profile picture, banner, display name and bio will **not** be updated on the Fediverse account. However, it will still gather and post the tweets following your config's parameters.\n\nNOTE: An ```error.log``` file will be created at the path from which ```pleroma-bot``` is being called.\n\n### crontab entry example \n**(everyday at 6:15 AM)** update profile and **(every 10 min.)** post new tweets:\n```bash\n# Post tweets every 10 min\n*/10 * * * * cd /home/robertoszek/myvenv/ \u0026\u0026 . bin/activate \u0026\u0026 pleroma-bot noProfile\n\n# Update pleroma profile with Twitter info every day at 6:15 AM\n15 6 * * * cd /home/robertoszek/myvenv/ \u0026\u0026 . bin/activate \u0026\u0026 pleroma-bot\n```\nNOTE: If you have issues with cron running the bot you may have to specify the full path of your Python executable\n\n```*/10 * * * * /usr/bin/python /usr/local/bin/pleroma-bot```\n\n## Screenshots\n\n![Screenshot](img/cmd.png)\n\n\n![Screenshot](img/screenshot.png)\n\n## Acknowledgements\nThese projects proved to be immensely useful, they are Python wrappers for the Mastodon API and Twitter API respectively:\n\n* [Mastodon.py](https://github.com/halcy/Mastodon.py)\n* [twitter-python](https://github.com/bear/python-twitter)\n\nThey were part of the impetus for this project, challenging myself to not just import them and use them, instead opting to directly do the heavy lifting with built-in python modules. \n\nThat and [mastodon-bot](https://github.com/yogthos/mastodon-bot) not working after upgrading the Pleroma instance I was admin on 😅. This event lead to repurposing this project (initially it only updated the profile info) and adding the tweet gathering and posting capabilities.\n\n## Contributing\n\nPatches, pull requests, and bug reports are more than [welcome](https://github.com/robertoszek/pleroma-bot/issues/new/choose), please keep the style consistent with the original source.\n\n\n## License\n\nMIT License\n\nCopyright (c) 2023 Roberto Chamorro / project contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n**Tested and confirmed working against** :\n* ```Pleroma BE 2.4.2```\n* ```Mastodon v3.2.1```\n* ```Misskey 12.110.1```\n* ```Twitter API v1.1 and v2```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertoszek%2Fpleroma-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobertoszek%2Fpleroma-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertoszek%2Fpleroma-bot/lists"}