# Sprawdzanie szablonów e-mail w CI

`bird email templates check` sprawdza szablony e-mail z dowolnego systemu CI i kończy się błędem, gdy zmiana mogłaby je uszkodzić, więc pull request wychwytuje problem, zanim zrobi to odbiorca. Polecenie tylko odczytuje: nic nie jest wysyłane i żadne wersje robocze się nie zmieniają.

## Zanim zaczniesz

- Zainstaluj [`bird` CLI](/docs/cli) z przypiętą wersją, aby nowe wydanie nigdy nie zmieniło Twojego pipeline'u bez zapowiedzi.
- Utwórz klucz API z dostępem do odczytu `email_management` i udostępnij go zadaniu jako `BIRD_API_KEY`.

## Sprawdzanie szablonu

```bash
bird email templates check welcome-email order-shipped
```

Polecenie renderuje wersję roboczą każdego szablonu we wszystkich jego językach, ponieważ tłumaczenie może się zepsuć niezależnie, i raportuje dla każdego szablonu i języka:

- **Obsługa klientów poczty**: te same wyniki zgodności, które pokazuje [podgląd szablonu](/docs/guides/email/templates), np. CSS usuwany lub ignorowany przez klienta.
- **Rozmiar**: treść HTML porównana z punktem obcinania Gmaila wynoszącym ok. 102 KB. Gmail ukrywa wszystko powyżej tego limitu za linkiem. Powyżej 90 KB sprawdzenie zgłasza ostrzeżenie, ponieważ wartości merge mogą przepchnąć wiadomość ponad limit.
- **Linki i obrazy**: każdy URL `http` i `https` w linku (`<a>` i `<area>`), źródle obrazu lub `srcset`, atrybucie `background` albo CSS `url()` w atrybucie `style` lub bloku `<style>`, pobierany z miejsca uruchomienia polecenia. `404`, `410` lub `5xx`, albo host, który nie istnieje, to problem. `401`, `403` lub `429`, albo zapytanie DNS, które przekroczyło limit czasu, to ostrzeżenie, ponieważ zwykle oznacza, że runner został odrzucony lub nie mógł dotrzeć do hosta. Linki do adresów prywatnych lub loopback nie są pobierane. Użyj `--skip-links` na runnerze bez wychodzącego dostępu do sieci.

Linki zbudowane ze zmiennej szablonu, pola kontaktu lub linku rezygnacji z subskrypcji nie są pobierane, ponieważ podgląd nie może wypełnić ich wartością, którą otrzyma odbiorca. Raport wymienia je w sekcji `unverified_links`, z częścią per odbiorca wyświetlaną jako `{variable}`, a `--annotations github` drukuje je jako powiadomienie, aby pull request pokazywał, co nie zostało sprawdzone.

Polecenie drukuje raport JSON na stdout: `valid` dla całego przebiegu, a następnie po jednym wpisie na szablon i język z jego `findings`. Każde znalezisko ma `severity`, `area` (`compatibility`, `size` lub `links`), `message` i zwykle `fix`. `problem` powoduje niepowodzenie sprawdzenia; `warning` jest raportowane i nigdy nie powoduje niepowodzenia.

## Sprawdzanie pliku renderowanego przez Twój build

Jeśli Twój build sam renderuje szablony, na przykład za pomocą MJML lub React Email, sprawdź plik, który generuje:

```bash
bird email templates check --html dist/welcome.html --template welcome-email --annotations github
```

Plik jest podglądany jako niezapisana treść względem szablonu, który wskażesz, więc wersje robocze się nie zmieniają; dowolny szablon zadziała. Z `--annotations github` wyniki zgodności trafiają na linie pliku, do których się odnoszą, a wyniki dotyczące rozmiaru i linków są oznaczane na pliku jako całości.

## Kody wyjścia

Kod wyjścia to wartość, na której opiera się Twoje zadanie CI:

| Kod wyjścia | Znaczenie                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| `0`         | Brak problemów. Ostrzeżenia nadal mogą być zgłaszane.                                                |
| `7`         | Sprawdzenie przebiegło i znalazło co najmniej jeden problem. Raport wymienia każdy z nich.           |
| `3`         | Szablon, który wskazałeś, nie istnieje w tym obszarze roboczym.                                      |
| `4`         | Klucz API nie istnieje, jest nieprawidłowy lub nie ma dostępu do odczytu `email_management`.         |
| `6`         | Ograniczenie liczby żądań lub tymczasowy błąd serwera. Spróbuj ponownie po opóźnieniu `retry_after`. |

Ponowne uruchomienie przy `7` bez wprowadzenia zmiany kończy się tak samo, więc warto ponawiać tylko `6`.

## Uruchamianie w GitHub Actions

Z `--annotations github` polecenie drukuje wyniki jako adnotacje GitHub Actions zamiast raportu JSON, więc pojawiają się one w sprawdzeniach pull requesta. Ten workflow sprawdza szablony renderowane przez Twój build przy każdym pull requeście, który je zmienia:

```yaml
name: Email templates
on:
  pull_request:
    paths: ["emails/**"]
jobs:
  check:
    # Pull requests from forks get no repository secrets, so the check could only exit 4.
    if: ${{ !github.event.pull_request.head.repo.fork }}
    runs-on: ubuntu-latest
    env:
      BIRD_API_KEY: ${{ secrets.BIRD_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Install the bird CLI
        run: curl -fsSL https://cli.bird.com/install.sh | sh -s -- --version "${{ vars.BIRD_CLI_VERSION }}"
      - name: Build the templates
        run: npm ci && npm run build:emails
      - name: Check the templates
        run: |
          status=0
          for file in dist/emails/*.html; do
            bird email templates check --html "$file" --template welcome-email --annotations github || status=$?
          done
          exit "$status"
```

Ustaw `BIRD_CLI_VERSION` jako zmienną repozytorium na wydanie, które przetestowałeś, a sekret `BIRD_API_KEY` na klucz z dostępem do odczytu `email_management`. GitHub nie udostępnia pull requestom z forków sekretów repozytorium, więc workflow je pomija. Sprawdź zmianę z forka przed mergem, wypychając tę samą zmianę do gałęzi w swoim repozytorium. W każdym innym systemie CI uruchom te same polecenia i zakończ zadanie błędem przy niezerowym kodzie wyjścia.

## Rozwiązywanie problemów

- **Wyjście `3`.** Szablon nie znajduje się w obszarze roboczym, do którego należy klucz API. Wylistuj szablony obszaru roboczego za pomocą `bird email templates list`.
- **Wyjście `4`.** Klucz nie ma dostępu do odczytu `email_management` lub sekret nie dociera do zadania.
- **Każdy link kończy się ostrzeżeniem.** Runner nie ma wychodzącego dostępu do sieci lub blokuje go zapora. Użyj `--skip-links` w tym środowisku, a linki sprawdzaj z runnera, który ma dostęp do internetu.

## Następne kroki

- [Szablony e-mail](/docs/guides/email/templates): twórz, podglądaj i publikuj szablony we wszystkich językach
- [`bird email templates check`](/docs/cli/reference/email-templates-check): wszystkie flagi polecenia
- [`bird` CLI](/docs/cli): instalacja przypiętej wersji i uwierzytelnianie w CI

## Related resources

- [Getting started with email](/learn/email/getting-started-with-email) (video)
- [Email](/email-api) (product)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=email)