Metadata-Version: 2.4
Name: github-email-alert
Version: 0.1.9
Summary: Reusable GitHub Email Alert package for CI/CD workflows
Author: Pandiyaraj Karuppasamy
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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

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

## Usage

### Basic Command

```bash
github-email-alert <branch_ref> <event_type>
```

### Version Information

To check the installed version:

```bash
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
```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
```

#### With Attachments
```bash
export ATTACHMENT_PATHS="report.pdf,logs.txt"
github-email-alert feature/login new_pr
```

### 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
```

#### Advanced Example: With Custom Sender and Attachments
```yaml
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.
