github-email-alert 0.1.6

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:
  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

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.