GitHub Notify

The easiest way to send GitHub repository notifications to Telegram!

Reusable GitHub Actions workflows that make it incredibly simple to get notified about Pull Requests, CI/CD status, releases, and other repository events. Just a few lines of code - no complex configuration needed!

Documentation

GitHub Notify is a reusable GitHub Action that allows you to send notifications to Telegram when specific events occur in your repository. This action can be integrated into your GitHub Actions workflows to notify you about Pull Requests, CI/CD pipeline status, releases, and other repository events.

How It Works

GitHub Notify provides reusable workflows that make it incredibly easy to send notifications to Telegram. Simply call our pre-built workflows with just a few lines of code - no need to write complex message templates or configure multiple steps.

The system uses the Telegram Bot API to send messages to your Telegram chat, group, or channel. When configured in your GitHub Actions workflow, it will automatically send beautifully formatted notifications whenever the workflow is triggered (e.g., on push, pull request, release, etc.).

How Reusable Workflows Work:

1. You create a simple workflow file in your repository
2. You call our reusable workflow with your chat ID and bot token
3. Our workflow handles all the formatting and message creation automatically
4. You receive a beautifully formatted notification in Telegram

Coming Soon Features:

• More pre-built reusable workflows for different event types (push, release, CI/CD, issues, etc.)
• Support for multiple notification channels (Slack, Discord, Email, etc.)
• Rich message formatting with attachments and media
• Customizable message templates for different event types
• Webhook support for real-time notifications
• Notification filtering and routing based on event types
• Integration with GitHub's native notification system
• Support for scheduled notifications and digest summaries

Prerequisites

Before using this action, you need to:

1. Create a Telegram bot and obtain a bot token
2. Get the chat ID where you want to receive notifications
3. Configure GitHub secrets for secure token storage

---

Step 1: Create a Telegram Bot

To create a Telegram bot, you need to interact with BotFather, Telegram's official bot for creating and managing bots.

Getting Your Bot Token

1. Open Telegram and search for @BotFather in the search bar
2. Start a conversation with BotFather by clicking "Start" or sending /start
3. Create a new bot by sending the command /newbot
4. Choose a name for your bot (e.g., "My GitHub Notifier")
5. Choose a username for your bot (must end with bot, e.g., my_github_notifier_bot)
6. Copy the bot token that BotFather provides you. It will look something like:

   123456789:ABCdefGHIjklMNOpqrsTUVwxyz
   

   ⚠️ Important: Keep this token secure and never commit it to your repository!

Bot Permissions

Your bot needs permission to send messages. If you're sending to a:

• Private chat: The bot can send messages directly to you
• Group: Add the bot to the group and make sure it has permission to send messages
• Channel: Add the bot as an administrator with permission to post messages

---

Step 2: Get Your Telegram Chat ID

The chat ID identifies where the bot should send messages. The method to get the chat ID depends on whether you're using a private chat, group, or channel.

Method 1: Get Your Personal Chat ID

1. Start a conversation with your bot by searching for it in Telegram and clicking "Start"
2. Send any message to your bot (e.g., "Hello")
3. Visit this URL in your browser (replace YOUR_BOT_TOKEN with your actual bot token):

   https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
   

4. Look for the chat object in the JSON response. The id field is your chat ID:

   {
     "ok": true,
     "result": [{
       "message": {
         "chat": {
           "id": 123456789,
           "first_name": "Your Name",
           "type": "private"
         }
       }
     }]
   }

5. Copy the chat ID (in this example: 123456789)

Method 2: Get a Group Chat ID

1. Add your bot to the group (search for your bot and add it)
2. Send a message in the group (any message will do)
3. Visit the same URL as above:

   https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
   

4. Find the group chat ID in the response. Group IDs are negative numbers (e.g., -1001234567890)

Method 3: Get a Channel Chat ID

1. Create or select a channel in Telegram

2. Add your bot as an administrator:

   • Go to channel settings
   • Click "Administrators"
   • Click "Add Administrator"
   • Select your bot
   • Make sure "Post Messages" permission is enabled

3. Post a message in the channel

4. Get the channel ID using one of these methods:

   Option A: Using the API

   • Visit: https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
   • Look for the channel ID (it will be negative, e.g., -1001234567890)

   Option B: Using a Telegram Bot

   • Forward a message from your channel to @userinfobot or @getidsbot
   • The bot will reply with the channel ID

   Option C: Using the Channel Username

   • If your channel is public, you can use the channel username (e.g., @my_channel)
   • For private channels, you must use the numeric ID

Quick Test

To verify everything is set up correctly, you can test sending a message using curl:

curl -X POST "https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage" \
  -d "chat_id=YOUR_CHAT_ID" \
  -d "text=Test message from GitHub Notify"

If successful, you should receive the message in your Telegram chat.

---

Step 3: Configure GitHub Secrets

To securely store your bot token and chat ID, you need to add them as GitHub Secrets in your repository.

Adding Secrets to Your Repository

1. Go to your GitHub repository on GitHub.com

2. Click on "Settings" (in the repository navigation bar)

3. Click on "Secrets and variables" → "Actions" (in the left sidebar)

4. Click "New repository secret"

5. Add the following secrets:

   Secret 1: TELEGRAM_BOT_TOKEN

   • Name: TELEGRAM_BOT_TOKEN
   • Value: Your bot token from BotFather (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
   • Click "Add secret"

   Secret 2: TELEGRAM_CHAT_ID

   • Name: TELEGRAM_CHAT_ID
   • Value: Your chat ID (e.g., 123456789 or -1001234567890)
   • Click "Add secret"

Adding Secrets to an Organization

If you want to use the same secrets across multiple repositories in an organization:

1. Go to your organization on GitHub.com
2. Click on "Settings"
3. Click on "Secrets and variables" → "Actions"
4. Click "New organization secret"
5. Add the secrets as described above
6. Configure repository access to specify which repositories can use these secrets

---

Step 4: Configure Your GitHub Actions Workflow

Now that you have your bot token and chat ID configured, you can use GitHub Notify in your workflows.

🎯 We highly recommend using our pre-built reusable workflows - they're the easiest and fastest way to get started! Just a few lines of code and you're done. No need to write complex message templates or worry about formatting.

---

🚀 Quick Start: Using Reusable Workflows (Recommended)

This is the easiest and fastest way to get started! Simply create a workflow file and call our reusable workflow - no need to write complex message templates or configure multiple steps.

Pull Request Notifications

Create a workflow file in your repository at .github/workflows/notify-pr.yml:

name: Notify PR via Telegram

on:
  pull_request_target:
    types:
      - opened

jobs:
  notify:
    uses: jobmetric/github-notify/.github/workflows/telegram-open-pull-request-notify.yml@master
    secrets:
      bot_token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
      chat_id: ${{ secrets.TELEGRAM_CHAT_ID }}

That's it! 🎉 This workflow will automatically send beautifully formatted notifications to your Telegram whenever:

• A pull request is opened

The notification includes:

• PR title and author
• Repository and PR number
• PR description (body)
• Creation time
• Direct link to the pull request

How to Use Reusable Workflows

1. Create a workflow file in your repository:

   • Go to your repository on GitHub
   • Click on the .github folder (create it if it doesn't exist)
   • Click on the workflows folder (create it if it doesn't exist)
   • Click "Add file" → "Create new file"
   • Name it something like notify-pr.yml

2. Copy and paste the workflow code (like the example above)

3. Make sure your secrets are configured (from Step 3 above)

4. Commit the file - GitHub Actions will automatically detect and run it

Important Notes:

• Use the version tag (e.g., @master) for the latest version
• Both bot_token and chat_id must be passed as secrets (never hardcode them!)
• The workflow uses pull_request_target event type to ensure it has access to the repository secrets
• Currently supports opened event type for pull requests

More Reusable Workflows Coming Soon

We're working on more pre-built workflows for:

• Push notifications
• Release notifications
• CI/CD status notifications
• Issue notifications
• And more!

---

---

Troubleshooting

Bot Not Sending Messages

1. Verify bot token: Make sure the token is correct and hasn't been revoked
2. Check chat ID: Ensure the chat ID is correct (positive for users, negative for groups/channels)
3. Bot permissions: For groups/channels, ensure the bot has permission to send messages
4. Start the bot: For private chats, make sure you've started a conversation with the bot

Getting 401 Unauthorized Error

• Your bot token is incorrect or has been revoked
• Regenerate the token from BotFather and update your GitHub secret

Getting 400 Bad Request Error

• Check that your chat ID is correct
• Verify the message format matches the parse mode you're using
• Ensure special characters are properly escaped (especially for MarkdownV2)

Messages Not Appearing in Channel

• Make sure the bot is added as an administrator to the channel
• Verify the bot has "Post Messages" permission enabled
• Check that you're using the correct channel ID (not the username for private channels)

---

Security Best Practices

1. Never commit secrets: Always use GitHub Secrets, never hardcode tokens in workflow files
2. Use organization secrets: For multiple repositories, use organization-level secrets
3. Rotate tokens regularly: Periodically regenerate your bot token for security
4. Limit bot permissions: Only grant the minimum permissions necessary
5. Review workflow files: Regularly audit your workflow files for security issues

---

Examples Repository

For more examples and use cases, check out the examples directory in the repository.

---

Support

If you encounter any issues or have questions:

1. Check the Troubleshooting section above
2. Search existing Issues
3. Create a new Issue with details about your problem

---

Roadmap

Coming Soon:

• Support for multiple notification channels (Slack, Discord, Email, etc.)
• Rich message formatting with attachments and media
• Customizable message templates for different event types
• Webhook support for real-time notifications
• Notification filtering and routing based on event types
• Integration with GitHub's native notification system
• Support for scheduled notifications and digest summaries
• Interactive buttons and inline keyboards in Telegram messages
• Support for sending files and media (images, documents, etc.)
• Rate limiting and retry mechanisms for reliable delivery

Contributing

Thank you for considering contributing to GitHub Notify! See the CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.