github-email-alert 0.1.2

Reusable GitHub Email Alert package for CI/CD workflows

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

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>

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

GitHub Actions Workflow Examples

Branch Created/Deleted Workflow

name: Branch Notification

on:
  create:
    branches: ['**']
  delete:
    branches: ['**']

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Send branch created notification
        if: github.event.action == 'created'
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          GITHUB_ACTOR: ${{ github.actor }}
          BASE_REF: ${{ github.event.ref }}
          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.action == 'deleted'
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          GITHUB_ACTOR: ${{ github.actor }}
          BASE_REF: main
          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:
      - uses: actions/checkout@v3
      
      - 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 }}
          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: [synchronize, opened]

jobs:
  check-conflict:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Check for merge conflicts
        id: check
        run: |
          git fetch origin ${{ github.event.pull_request.base.ref }}
          git merge --no-commit --no-ff origin/${{ github.event.pull_request.base.ref }} || echo "conflict=true" >> $GITHUB_OUTPUT
      
      - name: Send conflict notification
        if: steps.check.outputs.conflict == 'true'
        env:
          EMAIL_USER: ${{ secrets.EMAIL_USER }}
          EMAIL_PASS: ${{ secrets.EMAIL_PASS }}
          EMAIL_TO: ${{ secrets.EMAIL_TO }}
          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 }} conflict

Configuration

Required Environment Variables

EMAIL_USER          # SMTP email address (e.g., [e-mail])
EMAIL_PASS          # SMTP password or app-specific password
EMAIL_TO            # Comma-separated list of recipient emails

Optional Environment Variables

EMAIL_CC            # Comma-separated list of CC emails
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")

Note

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