Email Notifications

GitHub Star Tracker includes built-in email notification support via SMTP. Get notified when star counts change, with configurable thresholds and HTML reports.

Overview

Email notifications provide:

HTML-formatted reports with star changes
Visual charts and trend data
Configurable notification thresholds
Support for any SMTP provider
Optional notifications even when no changes occur

Basic SMTP Setup

To enable email notifications, configure SMTP settings in your workflow:

- uses: fbuireu/github-star-tracker@v1
  with:
    github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}
    
    # SMTP Configuration
    smtp-host: 'smtp.gmail.com'
    smtp-port: '587'
    smtp-username: ${{ secrets.SMTP_USERNAME }}
    smtp-password: ${{ secrets.SMTP_PASSWORD }}
    
    # Email Settings
    email-to: '[email protected]'
    email-from: 'GitHub Star Tracker'

Store SMTP credentials as repository secrets, never in plaintext in workflow files.

Adding SMTP Secrets

Navigate to Repository Settings

Go to your repository > Settings > Secrets and variables > Actions

Add SMTP Username

Click New repository secret
Name: SMTP_USERNAME
Value: Your SMTP username (often your email address)
Click Add secret

Add SMTP Password

Click New repository secret
Name: SMTP_PASSWORD
Value: Your SMTP password or app-specific password
Click Add secret

SMTP Provider Configuration

Gmail

Enable 2-Factor Authentication

Gmail requires 2FA to use app passwords. Enable it in Google Account Settings.

Generate App Password

Go to App Passwords
Select Mail and Other (Custom name)
Name it “GitHub Star Tracker”
Copy the generated 16-character password

Configure Workflow

smtp-host: 'smtp.gmail.com'
smtp-port: '587'
smtp-username: ${{ secrets.SMTP_USERNAME }}  # your Gmail address
smtp-password: ${{ secrets.SMTP_PASSWORD }}  # app password
email-to: '[email protected]'

Outlook / Office 365

smtp-host: 'smtp.office365.com'
smtp-port: '587'
smtp-username: ${{ secrets.SMTP_USERNAME }}  # your Outlook email
smtp-password: ${{ secrets.SMTP_PASSWORD }}  # your password
email-to: '[email protected]'

SendGrid

smtp-host: 'smtp.sendgrid.net'
smtp-port: '587'
smtp-username: 'apikey'  # Literal string 'apikey'
smtp-password: ${{ secrets.SENDGRID_API_KEY }}  # Your SendGrid API key
email-to: '[email protected]'
email-from: '[email protected]'

Amazon SES

smtp-host: 'email-smtp.us-east-1.amazonaws.com'  # Your SES region
smtp-port: '587'
smtp-username: ${{ secrets.SES_SMTP_USERNAME }}  # SES SMTP credentials
smtp-password: ${{ secrets.SES_SMTP_PASSWORD }}
email-to: '[email protected]'
email-from: '[email protected]'  # Must be verified in SES

Custom SMTP Server

smtp-host: 'mail.yourdomain.com'
smtp-port: '587'  # or 465 for SSL
smtp-username: ${{ secrets.SMTP_USERNAME }}
smtp-password: ${{ secrets.SMTP_PASSWORD }}
email-to: '[email protected]'
email-from: 'Star Tracker <[email protected]>'

Port Configuration

Star Tracker supports standard SMTP ports:

Port	Security	Usage
`587`	STARTTLS	Recommended for most providers (default)
`465`	SSL/TLS	Direct SSL connection
`25`	None/STARTTLS	Legacy, often blocked by cloud providers

The action automatically detects SSL mode when using port 465. From the source code (src/infrastructure/notification/email.ts:55-60):

const secure = emailConfig.port === SECURE_SMTP_PORT;  // 465

const transporter = nodemailer.createTransport({
  host: emailConfig.host,
  port: emailConfig.port,
  secure,  // true if port 465
  // ...
});

Notification Thresholds

Control when notifications are sent based on star changes:

Send Every Run

notification-threshold: '0'
send-on-no-changes: true  # Send even if no stars changed

Send on Specific Threshold

notification-threshold: '5'  # Only notify if 5+ stars changed

Adaptive Threshold

notification-threshold: 'auto'  # Automatically adjusts based on history

The auto mode intelligently determines when to notify based on historical patterns.

Conditional Notifications

Use workflow conditions for more control:

- name: Track stars
  id: tracker
  uses: fbuireu/github-star-tracker@v1
  with:
    github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}
    smtp-host: 'smtp.gmail.com'
    smtp-port: '587'
    smtp-username: ${{ secrets.SMTP_USERNAME }}
    smtp-password: ${{ secrets.SMTP_PASSWORD }}
    email-to: '[email protected]'
    notification-threshold: '0'

# Only send if significant changes
- name: Send special notification
  if: steps.tracker.outputs.new-stars >= 10
  run: |
    echo "Major milestone: 10+ new stars!"
    # Custom notification logic here

Email Content

Email notifications include:

Subject Line: Summary of star changes (e.g., “Star Update: +5 stars”)
HTML Report: Formatted tables with:
- Total star count
- New stars gained
- Stars lost
- Repository breakdown
- Star change delta per repository
Charts: Embedded SVG charts (if include-charts: true)
Stargazer Info: New stargazers (if track-stargazers: true)

Complete Example

Full workflow configuration with email notifications:

name: Track Stars with Email

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

permissions:
  contents: write

jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - name: Track stars and notify
        uses: fbuireu/github-star-tracker@v1
        with:
          # Authentication
          github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}
          
          # Repository settings
          visibility: 'public'
          include-charts: true
          track-stargazers: true
          locale: 'en'
          
          # SMTP Configuration
          smtp-host: 'smtp.gmail.com'
          smtp-port: '587'
          smtp-username: ${{ secrets.SMTP_USERNAME }}
          smtp-password: ${{ secrets.SMTP_PASSWORD }}
          
          # Email Settings
          email-to: '[email protected]'
          email-from: 'GitHub Star Tracker'
          notification-threshold: 'auto'
          send-on-no-changes: false

Testing Email Configuration

Test your email setup:

Run Workflow Manually

Go to Actions > Your Workflow > Run workflow

Check Workflow Logs

Look for email-related messages in the logs:

Email sent: <message-id>

Verify Email Delivery

Check your inbox and spam folder for the notification email.

Enable Debug Logging (if needed)

Add send-on-no-changes: true to force sending an email even with no changes.

Troubleshooting

Email Not Received

Check Spam Folder

SMTP emails may be filtered as spam. Check your spam/junk folder and mark as “Not Spam” if found.

Verify SMTP Credentials

Ensure SMTP username and password are correct
For Gmail, use app-specific password, not your regular password
Check that secrets are properly configured

Check Workflow Logs

Look for errors in workflow logs:

SMTP configured but no email-to address provided
Authentication failed
Connection timeout

Verify Notification Threshold

If no email is sent, check if the threshold was met:

Use notification-threshold: '0' to send on every run
Set send-on-no-changes: true for testing

Authentication Errors

Gmail “Less secure app access” error:

Enable 2-Factor Authentication
Use App Password instead of regular password
Ensure “Less secure app access” is not required

Outlook authentication failed:

Verify account credentials
Check if account has 2FA enabled (may need app password)
Ensure SMTP access is not disabled by organization

SendGrid authentication:

Username must be the literal string apikey
Password must be a valid SendGrid API key
Verify API key has Mail Send permissions

Connection Issues

Port blocked:

Try port 587 (STARTTLS) as default
Try port 465 (SSL) if 587 is blocked
Check if your hosting provider blocks SMTP ports

Timeout errors:

Verify SMTP host address is correct
Check firewall/network restrictions
Try different SMTP port

Alternative Notification Methods

If you prefer not to use built-in SMTP, integrate with external services:

Using GitHub Actions Email Action

- name: Track stars
  id: tracker
  uses: fbuireu/github-star-tracker@v1
  with:
    github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}

- name: Send email
  if: steps.tracker.outputs.should-notify == 'true'
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 587
    username: ${{ secrets.SMTP_USERNAME }}
    password: ${{ secrets.SMTP_PASSWORD }}
    subject: Star Tracker Report
    body: ${{ steps.tracker.outputs.report-html }}
    to: [email protected]
    from: GitHub Star Tracker
    content_type: text/html

Using Slack Notifications

- name: Track stars
  id: tracker
  uses: fbuireu/github-star-tracker@v1
  with:
    github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}

- name: Notify Slack
  if: steps.tracker.outputs.stars-changed == 'true'
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "⭐ Star Update",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "Total: *${{ steps.tracker.outputs.total-stars }}* stars\nNew: *+${{ steps.tracker.outputs.new-stars }}*\nLost: *-${{ steps.tracker.outputs.lost-stars }}*"
            }
          }
        ]
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Using Discord Webhooks

- name: Track stars
  id: tracker
  uses: fbuireu/github-star-tracker@v1
  with:
    github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}

- name: Discord notification
  if: steps.tracker.outputs.should-notify == 'true'
  uses: sarisia/actions-status-discord@v1
  with:
    webhook: ${{ secrets.DISCORD_WEBHOOK }}
    title: "GitHub Star Tracker Report"
    description: |
      **Total Stars:** ${{ steps.tracker.outputs.total-stars }}
      **New Stars:** +${{ steps.tracker.outputs.new-stars }}
      **Lost Stars:** -${{ steps.tracker.outputs.lost-stars }}
    color: 0xFFAC33

Get Started

Core Concepts

Configuration

Features

Guides

Overview

Basic SMTP Setup

Adding SMTP Secrets

SMTP Provider Configuration

Gmail

Outlook / Office 365

SendGrid

Amazon SES

Custom SMTP Server

Port Configuration

Notification Thresholds

Send Every Run

Send on Specific Threshold

Adaptive Threshold

Conditional Notifications

Email Content

Complete Example

Testing Email Configuration

Troubleshooting

Email Not Received

Authentication Errors

Connection Issues

Alternative Notification Methods

Using GitHub Actions Email Action

Using Slack Notifications

Using Discord Webhooks

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Features

Guides

​Overview

​Basic SMTP Setup

​Adding SMTP Secrets

​SMTP Provider Configuration

​Gmail

​Outlook / Office 365

​SendGrid

​Amazon SES

​Custom SMTP Server

​Port Configuration

​Notification Thresholds

​Send Every Run

​Send on Specific Threshold

​Adaptive Threshold

​Conditional Notifications

​Email Content

​Complete Example

​Testing Email Configuration

​Troubleshooting

​Email Not Received

​Authentication Errors

​Connection Issues

​Alternative Notification Methods

​Using GitHub Actions Email Action

​Using Slack Notifications

​Using Discord Webhooks

​Related Resources

Build docs developers (and LLMs) love

Overview

Basic SMTP Setup

Adding SMTP Secrets

SMTP Provider Configuration

Gmail

Outlook / Office 365

SendGrid

Amazon SES

Custom SMTP Server

Port Configuration

Notification Thresholds

Send Every Run

Send on Specific Threshold

Adaptive Threshold

Conditional Notifications

Email Content

Complete Example

Testing Email Configuration

Troubleshooting

Email Not Received

Authentication Errors

Connection Issues

Alternative Notification Methods

Using GitHub Actions Email Action

Using Slack Notifications

Using Discord Webhooks

Related Resources