GitHub Actions¶

Пошаговая инструкция по проверке исходящей почты в GitHub Actions с Mailexam^®. Приложение отправляет письмо по SMTP; pipeline ждёт доставку и проверяет тему и тело через mailexam-cli.

Эталонный репозиторий: github.com/mailexam/GitHub-Actions

Что понадобится¶

Аккаунт Mailexam^® и проект с SMTP-учётными данными.
API-токен из личного кабинета — только для CLI, не для SMTP.
Репозиторий на GitHub с включёнными Actions.

Из приветственного письма (или кабинета) для проекта:

ВАШ_ЛОГИН — SMTP-логин (например, xxxxx);
ВАШ_ПАРОЛЬ — SMTP-пароль (уникальная пара с логином);
хост — ВАШ_ЛОГИН.mailexam.ru (совпадает с логином).

Зачем Mailexam в CI¶

На shared runner GitHub рядом с приложением нет локального Mailpit или MailHog. Mailexam принимает SMTP с любого runner и отдаёт письма в браузере и через REST API. См. MailHog/Mailpit или Mailexam.

Секреты и переменные¶

Settings → Secrets and variables → Actions.

SecretsVariables

Имя	Описание
`MAILEXAM_API_TOKEN`	API-токен для mailexam-cli
`MAILEXAM_LOGIN`	SMTP-логин из приветственного письма
`MAILEXAM_PASSWORD`	SMTP-пароль (пара к логину)

Имя	Описание
`MAILEXAM_PROJECT_UUID`	UUID проекта — кабинет или `mailexam project list`

SMTP и API-токен

MAILEXAM_LOGIN / MAILEXAM_PASSWORD — для отправки письма приложением. MAILEXAM_API_TOKEN — для чтения письма CLI. Не путайте их.

Pull request из fork

GitHub не передаёт секреты репозитория в workflow, запущенные из PR fork. Используйте workflow_dispatch, push в свои ветки или отдельный тестовый репозиторий.

Типичный сценарий¶

sequenceDiagram
    participant App as Приложение / скрипт
    participant SMTP as Mailexam SMTP
    participant GHA as GitHub Actions
    participant CLI as mailexam CLI
    participant API as REST API

    GHA->>App: тесты / отправка
    App->>SMTP: sendMail()
    Note over SMTP: Письмо в sandbox
    GHA->>CLI: mailexam email assert
    CLI->>API: polling GET /email
    API-->>CLI: письмо найдено
    CLI->>CLI: проверка темы, тела
    Note over CLI: exit 0 или 1

Шаг job отправляет письмо по SMTP (приложение или тестовый скрипт).
Следующий шаг запускает mailexam email wait или mailexam email assert.
Ненулевой exit code падает job — обёртка не нужна.

Эталонный workflow¶

Полный рабочий пример — в mailexam/GitHub-Actions:

name: Mailexam email test

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  email-test:
    runs-on: ubuntu-latest
    env:
      MAILEXAM_API_BASE: https://mailexam.ru/api/v1
      MAILEXAM_PROJECT_UUID: ${{ vars.MAILEXAM_PROJECT_UUID }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Send test email
        env:
          MAILEXAM_LOGIN: ${{ secrets.MAILEXAM_LOGIN }}
          MAILEXAM_PASSWORD: ${{ secrets.MAILEXAM_PASSWORD }}
          MAILEXAM_PORT: '587'
        run: npm run send-test-email

      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Install mailexam CLI
        run: go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest

      - name: Add Go bin to PATH
        run: echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"

      - name: Assert email delivered
        env:
          MAILEXAM_API_TOKEN: ${{ secrets.MAILEXAM_API_TOKEN }}
        run: >
          mailexam email assert
          --subject "GitHub Actions + Mailexam"
          --contains "Mailexam CI check"

Скопируйте .github/workflows/mailexam.yml и scripts/send-test-email.js в свой репозиторий (для .ru замените SMTP-хост на ВАШ_ЛОГИН.mailexam.ru в скрипте).

SMTP для приложения¶

Передайте SMTP-учётные данные в env job, чтобы тесты шли в Mailexam, а не в реальный ящик:

env:
  MAILEXAM_LOGIN: ${{ secrets.MAILEXAM_LOGIN }}
  MAILEXAM_PASSWORD: ${{ secrets.MAILEXAM_PASSWORD }}
  MAIL_HOST: ${{ secrets.MAILEXAM_LOGIN }}.mailexam.ru
  MAIL_PORT: '587'

Маппинг .env по фреймворкам — в примерах интеграции (Laravel, Django, Express и др.).

mailexam-cli в pipeline¶

Установите Go 1.22+, затем:

- uses: actions/setup-go@v5
  with:
    go-version: '1.22'
- run: go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest
- run: echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"

Типичная проверка:

mailexam email assert --subject "Заказ оформлен" --contains "Спасибо"
mailexam email assert --subject "Код" --contains "123456" --timeout 60

Справочник команд и exit codes: Интерфейс командной строки (CLI).

Environments (опционально)¶

Для staging и production создайте Environments в GitHub (Settings → Environments) с разными секретами и MAILEXAM_PROJECT_UUID:

jobs:
  email-test:
    runs-on: ubuntu-latest
    environment: staging

Частые проблемы¶

api token is required

Добавьте MAILEXAM_API_TOKEN в Secrets репозитория или передайте --token.

Exit code 2 (403)

Токен неверный или от другого аккаунта. См. REST API — типичные проблемы.

Exit code 3 (timeout)

Увеличьте --timeout — на «холодном» runner SMTP может идти несколько секунд.
Проверьте, что MAILEXAM_PROJECT_UUID соответствует проекту SMTP-логина.

mailexam: command not found

Добавьте $(go env GOPATH)/bin в PATH после go install (см. workflow выше).

Ошибки SMTP-соединения

Хост: ВАШ_ЛОГИН.mailexam.ru — тот же логин, что в MAILEXAM_LOGIN, без префикса smtp..
Порт 587 с STARTTLS.