Email Notifications

​

Setup Overview

1. Configure SMTP server settings
2. Provide sender and recipient email addresses
3. (Optional) Configure notification threshold

​

SMTP Configuration

​

Required SMTP Settings

with:
  smtp-host: smtp.gmail.com

with:
  smtp-username: ${{ secrets.SMTP_USERNAME }}

with:
  smtp-password: ${{ secrets.SMTP_PASSWORD }}

with:
  email-to: [email protected]

​

Optional SMTP Settings

with:
  smtp-port: 587

with:
  email-from: Star Tracker <[email protected]>

​

Provider-Specific Setup

​

Gmail

1. Enable 2-factor authentication on your Google account
2. Generate an app password at myaccount.google.com/apppasswords
3. Use these settings:

with:
  smtp-host: smtp.gmail.com
  smtp-port: 587
  smtp-username: [email protected]
  smtp-password: ${{ secrets.GMAIL_APP_PASSWORD }}
  email-from: Your Name <[email protected]>
  email-to: [email protected]

​

Outlook / Office 365

with:
  smtp-host: smtp.office365.com
  smtp-port: 587
  smtp-username: [email protected]
  smtp-password: ${{ secrets.OUTLOOK_PASSWORD }}
  email-from: [email protected]
  email-to: [email protected]

​

SendGrid

with:
  smtp-host: smtp.sendgrid.net
  smtp-port: 587
  smtp-username: apikey
  smtp-password: ${{ secrets.SENDGRID_API_KEY }}
  email-from: [email protected]
  email-to: [email protected]

​

AWS SES

with:
  smtp-host: email-smtp.us-east-1.amazonaws.com
  smtp-port: 587
  smtp-username: ${{ secrets.AWS_SMTP_USERNAME }}
  smtp-password: ${{ secrets.AWS_SMTP_PASSWORD }}
  email-from: [email protected]
  email-to: [email protected]

​

Mailgun

with:
  smtp-host: smtp.mailgun.org
  smtp-port: 587
  smtp-username: [email protected]
  smtp-password: ${{ secrets.MAILGUN_PASSWORD }}
  email-from: [email protected]
  email-to: [email protected]

​

Notification Thresholds

​

Threshold Options

with:
  notification-threshold: auto

with:
  notification-threshold: 0

with:
  notification-threshold: 5

​

Send on No Changes

with:
  send-on-no-changes: true

• Emails are sent even when no stars have changed
• Useful for periodic status reports
• The report will indicate “no changes” in the summary

​

Email Content

• Subject line: Localized subject with total stars and change delta
• HTML report: Formatted report with:
  • Summary of star changes
  • Repository breakdown
  • Star trend charts (if include-charts: true)
  • New and removed repositories
  • Individual repository trends
  • New stargazers (if track-stargazers: true)
  • Growth forecast

​

Subject Line Format

GitHub Star Tracker Report: 1,234 stars (+12)

• English: GitHub Star Tracker Report: {total} ({delta})
• Spanish: Informe de Seguimiento de Estrellas en GitHub: {total} ({delta})
• Catalan: Informe de Seguiment d'Estrelles a GitHub: {total} ({delta})
• Italian: Report Tracciamento Stelle GitHub: {total} ({delta})

​

Complete Examples

​

Basic Email Notifications

name: Track Stars with Email

on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
  workflow_dispatch:

jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Track stars
        uses: fbuireu/github-star-tracker@v2
        with:
          github-token: ${{ secrets.PAT_TOKEN }}
          
          # SMTP Configuration
          smtp-host: smtp.gmail.com
          smtp-port: 587
          smtp-username: ${{ secrets.SMTP_USERNAME }}
          smtp-password: ${{ secrets.SMTP_PASSWORD }}
          email-to: [email protected]
          email-from: GitHub Stars
          
          # Notification settings
          notification-threshold: auto

​

Advanced Notifications with Custom Threshold

name: Track Stars - High Activity

on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
  workflow_dispatch:

jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Track stars
        uses: fbuireu/github-star-tracker@v2
        with:
          github-token: ${{ secrets.PAT_TOKEN }}
          
          # Repository filters
          visibility: public
          min-stars: 10
          
          # SMTP Configuration
          smtp-host: smtp.sendgrid.net
          smtp-port: 587
          smtp-username: apikey
          smtp-password: ${{ secrets.SENDGRID_API_KEY }}
          email-to: [email protected]
          email-from: Popular Repos <[email protected]>
          
          # Notification settings
          notification-threshold: 10  # Only notify for 10+ star changes
          send-on-no-changes: false
          
          # Report settings
          include-charts: true
          locale: en
          track-stargazers: true

​

Multiple Recipients (Using SendGrid)

with:
  smtp-host: smtp.sendgrid.net
  smtp-port: 587
  smtp-username: apikey
  smtp-password: ${{ secrets.SENDGRID_API_KEY }}
  email-from: [email protected]
  email-to: [email protected],[email protected]  # Multiple recipients

​

Troubleshooting

​

Email Not Sending

1. Check credentials: Verify SMTP username and password are correct
2. Check port: Ensure you’re using the correct port (587 for TLS)
3. Check logs: Review the GitHub Actions logs for error messages
4. Test SMTP: Use a tool like telnet or openssl to test SMTP connectivity
5. App passwords: For Gmail and some providers, ensure you’re using app-specific passwords

​

Authentication Errors

• Gmail: Must use app password with 2FA enabled
• Office 365: May need to enable SMTP AUTH
• AWS SES: Must verify sending domain/email first

​

Notifications Not Triggering

1. Check threshold: Your notification-threshold might be too high
2. No changes: Enable send-on-no-changes: true to test
3. Check should-notify output: Review the action outputs in logs

​

Security Best Practices

1. Use GitHub Secrets: Store all SMTP credentials as repository secrets
2. Use app passwords: Enable 2FA and use app-specific passwords when available
3. Limit token scope: Use the minimum required GitHub token scope
4. Review access: Regularly review who has access to your secrets
5. Rotate credentials: Periodically update SMTP passwords and tokens

​

Setting Up Secrets

1. Go to your repository Settings > Secrets and variables > Actions
2. Click “New repository secret”
3. Add these secrets:
   • PAT_TOKEN - Your GitHub Personal Access Token
   • SMTP_USERNAME - Your SMTP username
   • SMTP_PASSWORD - Your SMTP password or app password

​

Next Steps