github-email-alert 0.1.3
Reusable GitHub Email Alert package for CI/CD workflows
Requires Python: >=3.8

# 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

```bash
pip install github-email-alert
```

## Usage

### Basic Command

```bash
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
```bash
github-email-alert feature/new-feature branch_create
```

#### Branch Deleted
```bash
github-email-alert feature/old-feature branch_delete
```

#### New Pull Request
```bash
github-email-alert feature/login new_pr
```

#### Pull Request Merged
```bash
github-email-alert feature/login merge_pr
```

#### Merge Conflict Detected
```bash
github-email-alert feature/login conflict
```

### GitHub Actions Workflow Examples

#### Branch Created/Deleted Workflow
```yaml
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
```yaml
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
```yaml
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., your-email@gmail.com)
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.