GitHub Email Alert

Reusable Python package to send email alerts from GitHub Actions.

Features

• Send alerts for:
  • Branch Created
  • Branch Deleted
  • New Pull Request
  • PR Merge
  • Merge Conflicts
• SMTP configurable
• CLI support
• Works with GitHub Actions
• CC support
• Environment variable driven
• Multipart email support (plain text + HTML)
• UTF-8 encoding for international character support
• File attachment support

Note: Branch create/delete events do not include a title field in the email body.

Installation

pip install github-email-alert

Usage

Basic Command

github-email-alert <branch_ref> <event_type>

Version Information

To check the installed version:

github-email-alert --version

Event Types

The following event types are supported:

• branch_create - Branch created event
• branch_delete - Branch deleted event
• new_pr - New pull request created
• merge_pr - Pull request merged
• conflict - Merge conflict detected

Examples

Branch Created

github-email-alert feature/new-feature branch_create

Branch Deleted

github-email-alert feature/old-feature branch_delete

New Pull Request

github-email-alert feature/login new_pr

Pull Request Merged

github-email-alert feature/login merge_pr

Merge Conflict Detected

github-email-alert feature/login conflict

With Attachments

export ATTACHMENT_PATHS="report.pdf,logs.txt"
github-email-alert feature/login new_pr

GitHub Actions Workflow Examples

Branch Created/Deleted Workflow

name: Branch Notification

on:
  create:
  delete:

jobs:
  notify:
    runs-on: ubuntu-latest

    steps:
      - name: Send branch created notification
        if: github.event_name == 'create' && github.event.ref_type == 'branch'
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          GITHUB_ACTOR: ${{ github.actor }}
          BASE_REF: ${{ github.event.repository.default_branch }}
          REPO_NAME: ${{ github.repository }}
        run: |
          pip install github-email-alert
          github-email-alert "${{ github.event.ref }}" branch_create

      - name: Send branch deleted notification
        if: github.event_name == 'delete' && github.event.ref_type == 'branch'
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          GITHUB_ACTOR: ${{ github.actor }}
          BASE_REF: ${{ github.event.repository.default_branch }}
          REPO_NAME: ${{ github.repository }}
        run: |
          pip install github-email-alert
          github-email-alert "${{ github.event.ref }}" branch_delete

Pull Request Workflow

name: PR Notification

on:
  pull_request:
    types: [opened, closed]

jobs:
  notify:
    runs-on: ubuntu-latest

    steps:
      - name: Send new PR notification
        if: github.event.action == 'opened'
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          EMAIL_CC: ${{ secrets.EMAIL_CC }}
          GITHUB_ACTOR: ${{ github.actor }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          BASE_REF: ${{ github.event.pull_request.base.ref }}
          REPO_NAME: ${{ github.repository }}
        run: |
          pip install github-email-alert
          github-email-alert "${{ github.event.pull_request.head.ref }}" new_pr

      - name: Send PR merged notification
        if: github.event.action == 'closed' && github.event.pull_request.merged == true
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          EMAIL_CC: ${{ secrets.EMAIL_CC }}
          GITHUB_ACTOR: ${{ github.actor }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          BASE_REF: ${{ github.event.pull_request.base.ref }}
          REPO_NAME: ${{ github.repository }}
        run: |
          pip install github-email-alert
          github-email-alert "${{ github.event.pull_request.head.ref }}" merge_pr

Merge Conflict Detection Workflow

name: Conflict Detection

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  check-conflict:
    runs-on: ubuntu-latest

    steps:
      - name: Report conflict
        if: github.event.pull_request.mergeable_state == 'dirty'
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          GITHUB_ACTOR: ${{ github.actor }}          
          REPO_NAME: ${{ github.repository }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          BRANCH_REF: ${{ github.event.pull_request.head.ref }}
          BASE_REF: ${{ github.event.pull_request.base.ref }}
          
        run: |
          pip install github-email-alert
          github-email-alert "${{ github.event.pull_request.head.ref }}" conflict

Advanced Example: With Custom Sender and Attachments

name: PR Notification with Attachments

on:
  pull_request:
    types: [opened]

jobs:
  notify:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Generate report
        run: |
          echo "Pull Request Report" > pr-report.txt
          echo "Branch: ${{ github.event.pull_request.head.ref }}" >> pr-report.txt
          
      - name: Send notification with attachment
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_FROM: ${{ secrets.EMAIL_FROM }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          EMAIL_CC: ${{ secrets.EMAIL_CC }}
          ATTACHMENT_PATHS: pr-report.txt
          GITHUB_ACTOR: ${{ github.actor }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          BASE_REF: ${{ github.event.pull_request.base.ref }}
          REPO_NAME: ${{ github.repository }}
        run: |
          pip install github-email-alert
          github-email-alert "${{ github.event.pull_request.head.ref }}" new_pr

Configuration

Required Environment Variables

EMAIL_USER          # SMTP email address for authentication (e.g., your-email@gmail.com)
EMAIL_PASS          # SMTP password or app-specific password
EMAIL_TO            # Comma-separated list of recipient emails

Optional Environment Variables

EMAIL_FROM          # Email address to use as sender (default: EMAIL_USER)
EMAIL_CC            # Comma-separated list of CC emails
ATTACHMENT_PATHS    # Comma-separated list of file paths to attach
SMTP_HOST           # SMTP server hostname (default: smtp.gmail.com)
SMTP_PORT           # SMTP server port (default: 587)
GITHUB_ACTOR        # GitHub username (default: "Unknown")
PR_TITLE            # Pull request title (default: "N/A")
BASE_REF            # Target/base branch name (default: "main")
REPO_NAME           # Repository name (default: "Unknown")

Email Configuration Notes

• EMAIL_USER is used for SMTP authentication (login credentials)
• EMAIL_FROM is optional and specifies the sender email address shown in the "From" field
• If EMAIL_FROM is not set, EMAIL_USER will be used as both the authentication account and sender address
• Use EMAIL_FROM when you want to send emails from a different address than your authentication account (e.g., sending from a group email while authenticating with your personal account)

Advanced Email Features

Multipart Email Support:

• All emails are sent with both plain text and HTML versions for better compatibility
• Email clients will automatically display the best version they support
• UTF-8 encoding is used throughout for international character support

Attachment Support:

• Set ATTACHMENT_PATHS environment variable with comma-separated file paths
• Example: ATTACHMENT_PATHS="report.pdf,logs.txt,screenshot.png"
• Files are attached as binary attachments
• If a file is not found, a warning is displayed but email sending continues

Note

Branch create/delete events do not include a title field in the email body since they don't have an associated pull request.