No server to maintain. No Instagram password. Powered by GitHub Actions + Apify.
Setup wizard · Get started · How it works · Costs · Troubleshooting
Illustration of the output, not a screenshot of a real Instagram account or Telegram channel.
| Feature | Default behavior |
|---|---|
| Automatic cross-posting | Checks a public Instagram profile approximately every 6 hours |
| Media | Photos, videos / Reels and mixed carousels (up to 20 items per Instagram post, split into albums of 10) |
| Captions | Preserves full text and links, using follow-up Telegram messages when needed |
| Duplicate protection | Tracks hashed identifiers and quarantines uncertain Telegram deliveries |
| No hosting | Scheduled workflow runs on GitHub Actions |
| Privacy | Bot and Apify tokens are stored in GitHub Actions Secrets |
| Safe setup | First-run baseline prevents a flood of old Instagram posts |
| Multiple accounts | Up to 20 public Instagram profiles, each mapped to a Telegram destination |
| Reporting | Run summaries: checks, published items, failures, conservative per-attempt Apify allowances |
| Flexible | Optional advanced backends for local use, separate from lightweight default |
The default workflow uses Apify Instagram Scraper and the Telegram Bot API. Apify is an external service that may charge for usage; read Costs and limits.
Prefer a guided setup? Try the interactive setup wizard. It generates a GitHub Actions account configuration in your browser, without collecting API tokens.
Create private copy · Interactive setup wizard
Choose Private on GitHub's creation page and create the repository. This avoids GitHub's specific 60-day inactivity cutoff for scheduled workflows in public repos and needs no extra cron service or fake commits. GitHub Free includes 2,000 monthly Actions minutes shared across your eligible private workflows; Apify is billed separately.
Public deployment? You can create a public copy or fork. Public copies need attention to GitHub's 60-day inactivity rule; public forks additionally start with scheduled Actions disabled. See private/public/keepalive/Cloudflare deployment options before choosing.
This template does not copy tokens or configure the bot automatically. Follow the steps below to add credentials and initialize it once.
In your copy, open Settings → Secrets and variables → Actions:
| Type | Name | Value |
|---|---|---|
| Variable | INSTAGRAM_USERNAME |
Public Instagram profile name, without @ |
| Variable | TELEGRAM_CHAT_ID |
Target channel username (e.g. @my_channel) or chat ID |
| Secret | TELEGRAM_BOT_TOKEN |
Token issued by @BotFather |
| Secret | APIFY_TOKEN |
Token from Apify Console |
Add the bot as an administrator of the destination channel, with permission to post messages. If posting to a group, grant the necessary permissions there instead.
Open Actions → Instagram to Telegram → Run workflow. Set initialize_only to true and run once. It records the current posts without sending them to Telegram.
Check that the run succeeds. Subsequent scheduled runs will check for new posts, typically every six hours. GitHub's schedule is best-effort, so it may start later than the exact cron time.
Want to test safely? Trigger the workflow with dry_run set to true. It fetches and checks media but does not publish to Telegram.
For a full walkthrough, common errors and local development, see Setup and troubleshooting.
flowchart LR
A[Public Instagram profile] --> B[Apify Scraper]
B --> C[Python sync]
C --> D{New and recent?}
D -->|Yes| E[Telegram Bot API]
D -->|No| F[Skip]
C <--> G[(Hashed sync state)]
The standard deployment uses GitHub Actions' built-in scheduler. No external cron service, webhook, or continuously running server is needed. The workflow's schedule trigger (17 */6 * * *, UTC) checks for new posts every six hours, even when nothing new has appeared on Instagram. You can also run a check manually via Actions → Instagram to Telegram → Run workflow. Scheduled starts are best-effort and can be delayed or missed.
Keeping the schedule active: In public repositories GitHub can disable scheduled workflows after 60 days without repository activity. The private template copy recommended above avoids that specific cutoff. A new Instagram post does not count as GitHub activity. If you choose a public deployment, see all maintenance options (community keepalive actions, manual re-enable, or an optional external Cloudflare Cron). None is currently enabled automatically in the template, and API keepalive is not a GitHub-guaranteed fix.
The action checks posts and Reels separately; it requests the additional details fallback only when a feed is missing or media appears low resolution. It considers up to six distinct candidates per run. It downloads eligible media and sends it to Telegram. State lives in a dedicated sync-state branch so automated state commits do not clutter the development history. The branch is created automatically on the first run.
The anti-duplicate logic rejects new candidates with missing timestamps, future timestamps or publication times older than 48 hours by default. This guards against a known Apify partial-failure case in which old Reels were returned as new content. You can change the threshold with apify.max_post_age_hours in config.example.yml (1–168 hours).
- Apify usage is separate from GitHub Actions. Check the Apify Instagram Scraper pricing and your account's current free credits before you run the workflow.
- The default configuration reserves a conservative allowance for every Apify request attempt and retry, capped at 1,800 requested results per billing cycle starting on day 26. This is a safety guard, not an invoice calculator or a guaranteed spending limit. Actor runs may have different billable usage.
- Each check uses posts and Reels requests; details requests are a conditional fallback. More frequent schedules and additional accounts may use more Apify credits.
- GitHub Actions and Telegram Bot API have their own platform limits. Large files and album sizes may exceed Telegram's restrictions.
- The default setup monitors one public Instagram account. The optional
ACCOUNTS_JSONvariable supports up to 20 distinct public accounts, each with its own destination. Stories and private accounts are unsupported.
Do not use this tool to repost material you do not have permission to redistribute. Respect Instagram's terms, Telegram's rules and the creator's rights.
The four repository values above work for one account. For multiple profiles, use the ACCOUNTS_JSON Actions variable generated by the wizard instead of the two single-account variables. Optionally configure ALERT_CHAT_ID for failure alerts after two consecutive failed sync runs. The Actions run summary includes privacy-safe aggregate activity counters. See config.example.yml for the schedule-independent settings: post scan depth, caption template, maximum age and Apify result cap.
Only PyYAML and requests are installed by the normal hosted workflow. Playwright, Telethon, Instaloader and curl_cffi remain optional for advanced local setups and are not used in the default production path.
python -m venv .venv
python -m pip install -r requirements-dev.txt
python -m pytest -qOnce the four environment variables are set:
python -m insta_tg_sync.cli --config config.example.yml --validate
python -m insta_tg_sync.cli --config config.example.yml --dry-runFor an extended outage, use Run workflow → catch_up_hours (48–168). Start with dry_run=true and verify which older posts would be sent before any real run. This does not bypass the candidate limit or undo entries already marked processed.
If Telegram delivery is uncertain, check your channel first. Then use Run workflow → resolve_action and choose delivered (mark processed) or retry (remove quarantine, no immediate post). Provide the Instagram username and shortcode from the original run log.
GitHub may disable scheduled workflows in public repositories with no activity for 60 days. We do not assume sync-state commits reset that clock. Check your copied repository's Actions tab and re-enable the workflow when needed.
Will the first run flood Telegram with old posts?
No. Run initialize_only first; a fresh state also has a first-run baseline safeguard.
Do I need to host anything?
No VPS is needed for the standard scheduled workflow. You do need your own GitHub repository and Apify account.
Do I need my Instagram password?
No. The standard backend accesses public data through Apify.
Can I customize captions?
Yes. Edit accounts[0].caption_template in config.example.yml.
Where are the secrets?
Use GitHub Actions Secrets. Never commit tokens or sessions. See SECURITY.md.
Does it support multiple Instagram accounts?
Yes. Use the setup wizard to create an ACCOUNTS_JSON variable. Each public Instagram account maps to one Telegram channel or group.
A real GitHub Actions dry-run shows Apify fetching, duplicate filtering and state persistence, without publishing to a real Telegram channel. The illustration above is a concept, not a screenshot.
Need better Instagram link previews in Telegram, Discord or Slack instead of automated channel reposting? See InstaFix Revived. It's an independent project for rich previews.
Found a bug? Open an issue with the sanitized workflow error, expected result and reproduction steps. Have an improvement? Read CONTRIBUTING.md.
See CHANGELOG.md for updates. MIT licensed.