Documentation
¶
Overview ¶
Tgfeed fetches RSS feeds and sends new articles via Telegram.
How it works? ¶
tgfeed runs as a GitHub Actions workflow.
It fetches RSS feeds from URLs provided in the feeds.json file on GitHub Gist that is a simple array of feed URLs:
[ "https://astrophena.name/feed.xml" ]
New articles are sent to a Telegram chat specified by the CHAT_ID environment variable.
Where it keeps state? ¶
tgfeed stores it's state on GitHub Gist.
It maintains a state for each feed, including last modified time, last updated time, ETag, error count, and last error message. It keeps track of failing feeds and disables them after a certain threshold of consecutive failures. State information is stored and updated in the state.json file on GitHub Gist. You won't need to touch this file at all, except from very rare cases.
Environment variables ¶
The tgfeed program relies on the following environment variables:
- CHAT_ID: Telegram chat ID where the program sends new articles.
- GIST_ID: GitHub Gist ID where the program stores its state.
- GITHUB_TOKEN: GitHub personal access token for accessing the GitHub API.
- TELEGRAM_TOKEN: Telegram bot token for accessing the Telegram Bot API.
- STATS_SPREADSHEET_ID: ID of the Google Spreadsheet to which the program uploads statistics for every run. This is required if the SERVICE_ACCOUNT_KEY is provided.
- SERVICE_ACCOUNT_KEY: JSON string representing the service account key for accessing the Google API. It's not required, and stats won't be uploaded to a spreadsheet if this variable is not set.
Stats collection ¶
tgfeed collects and reports stats about every run to Google Sheets. You can specify the ID of the spreadsheet via the STATS_SPREADSHEET_ID environment variable. To collect stats, you must provide the SERVICE_ACCOUNT_KEY environment variable with JSON string representing the service account key for accessing the Google API. Stats include:
- Total number of feeds fetched
- Number of successfully fetched feeds
- Number of feeds that failed to fetch
- Number of feeds that were not modified
- Start time of a run
- Duration of a run
- Number of parsed RSS items
- Total fetch time
- Average fetch time
- Memory usage
You can use these stats to monitor performance of tgfeed and understand which feeds are causing problems.
Administration ¶
To subscribe to a feed, you can use the -subscribe flag followed by the URL of the feed. For example:
$ tgfeed -subscribe https://example.com/feed
To unsubscribe from a feed, you can use the -unsubscribe flag followed by the URL of the feed. For example:
$ tgfeed -unsubscribe https://example.com/feed
To reenable a failing feed that has been disabled due to consecutive failures, you can use the -reenable flag followed by the URL of the feed. For example:
$ tgfeed -reenable https://example.com/feed
To view the list of feeds, you can use the -feeds flag. This will also print the URLs of feeds that have encountered errors during fetching. For example:
$ tgfeed -feeds
Source Files