Mercure-Hub: GitHub Actions & GitLab CI

Uruchom prawdziwą usługę Mercure Hub bezpośrednio z pipeline'u GitHub Actions lub GitLab CI, przetestuj ją, a następnie automatycznie ją usuń

👋 Witamy w dokumentacji Stackhero!

Stackhero oferuje gotowe do użycia rozwiązanie Mercure-Hub cloud, które zapewnia wiele korzyści, w tym:

Nieograniczone żądania i rozmiary wiadomości.

Dostosowywalna nazwa domeny zabezpieczona za pomocą HTTPS (na przykład, https://real-time.twoja-firma.com).

Łatwe aktualizacje za pomocą jednego kliknięcia.

Optymalna wydajność i solidne zabezpieczenia dzięki prywatnej i dedykowanej VM.

Dostępne w 🇪🇺 Europie i 🇺🇸 USA.

Oszczędzaj czas i upraszczaj sobie życie: wystarczy 5 minut, aby wypróbować rozwiązanie Mercure-Hub cloud hosting Stackhero!

Ten przewodnik przeprowadzi Cię przez proces uruchamiania rzeczywistej, dedykowanej usługi Mercure Hub w Twoim pipeline CI z wykorzystaniem GitHub Actions lub GitLab CI. Dzięki poniższym krokom możesz testować swój kod na żywej instancji Mercure Hub w warunkach zbliżonych do produkcyjnych, bez konieczności korzystania z mocków czy symulacji. Mercure Hub pushes real-time updates to browsers and clients over Server-Sent Events, with no polling and no custom websocket code.

Za każdym razem, gdy pipeline zostanie uruchomiony, otrzymasz nową instancję Mercure Hub. Oznacza to, że Twoje testy będą pracować z takim samym typem usługi, jaki zobaczą użytkownicy w środowisku produkcyjnym. Workflow automatycznie tworzy tymczasowy stack, dodaje usługę Mercure Hub, czeka na jej gotowość, pobiera wygenerowane dane dostępowe, wykonuje smoke test przy użyciu curl, a na końcu zawsze czyści wszystkie zasoby po zakończeniu działania.

Wykorzystasz Stackhero CLI, samodzielne narzędzie wiersza poleceń, które umożliwia szybkie i proste uruchamianie oraz zarządzanie usługami Stackhero.

1. Utwórz token dostępu i zapisz go jako sekret CI

Aby CLI mogło działać w trybie bezinteraktywnym, potrzebujesz tokena dostępu (format: usr-xxxxxx:tokenId). Token wystarczy utworzyć tylko raz, a następnie dodać go do pipeline'u CI jako bezpieczny, zaszyfrowany sekret.

Utwórz token: Na swoim dashboardzie Stackhero kliknij zdjęcie profilowe w prawym górnym rogu, przejdź do Twoje konto, następnie Access tokens i kliknij Create token.
Dla GitHub Actions: W repozytorium przejdź do Settings > Secrets and variables > Actions > New repository secret i wprowadź token jako STACKHERO_TOKEN.
Dla GitLab CI: W projekcie przejdź do Settings > CI/CD > Variables > Add variable, ustaw klucz na STACKHERO_TOKEN i zaznacz Masked (oraz Protected, jeśli pipeline uruchamiany jest tylko na chronionych branchach).

Nigdy nie umieszczaj tokena dostępu bezpośrednio w pliku YAML pipeline'u. Jeśli znajdzie się on w YAML, może być widoczny dla każdej osoby z dostępem do repozytorium i pojawić się w logach builda. Przechowywanie go jako sekret CI zapewnia szyfrowanie i maskowanie, dzięki czemu Twój token pozostaje bezpieczny.

2. Skrypt obsługujący cykl życia usługi

Poniżej znajdziesz kompletny przykład skryptu zarządzającego pełnym cyklem życia usługi. Pokazuje on, jak niewiele konfiguracji jest potrzebne – wystarczy kilka poleceń. Gotowe fragmenty YAML dla wybranej platformy znajdziesz w kolejnych sekcjach.

#!/bin/bash
set -euo pipefail

# STACKHERO_TOKEN jest przekazywany jako sekret CI, CLI wykrywa go automatycznie.

stackName="ci-mercure-hub-$$"          # Unikalna nazwa stacka dla każdego uruchomienia
serviceStore="mercure-hub"             # Store usługi Mercure Hub
instance="20G"        # Zmień w razie potrzeby (patrz krok 3)
region="europe"                         # Nazwa regionu (patrz stackhero regions-list)

# 1. Instalacja CLI na runnerze
curl -fsSL https://www.stackhero.io/install.sh | sh

# 2. Instalacja klienta wymaganego do smoke testu (jq + curl to podstawa)
apt-get update && apt-get install -y --no-install-recommends jq curl

# 3. Utworzenie dedykowanego stacka dla tego uruchomienia
stackId=$(stackhero --format=script stack-create --name="$stackName")
echo "Stack utworzony: $stackId"

# 4. Dodanie usługi Mercure Hub i pobranie jej service id
serviceId=$(stackhero --format=script service-add \
  --stack="$stackId" \
  --service-store="$serviceStore" \
  --instance="$instance" \
  --region="$region")
echo "Usługa dodana: $serviceId"

# 5. Oczekiwanie na uruchomienie usługi (może potrwać kilka minut)
stackhero service-wait-for --service="$serviceId"

# 6. Pobranie konfiguracji (zawiera wygenerowane dane dostępowe)
config=$(stackhero service-configuration-get --service="$serviceId" --format=json)

# 7. Wyodrębnienie potrzebnych danych dostępowych
host=$(echo "$config" | jq -r '.configuration.domain')

# 8. Smoke test: Request the hub endpoint and check it answers.
curl -fsS -o /dev/null -w "%{http_code}" "https://$host/.well-known/mercure?topic=test" | grep -qE "^(200|400|401)$"

echo "✅ Mercure Hub jest osiągalny z CI."

Krok usuwania, który kasuje usługę, czeka na jej usunięcie, a następnie usuwa stack, opisany jest w sekcjach specyficznych dla danej platformy poniżej. Takie podejście gwarantuje, że sprzątanie nastąpi zawsze, nawet jeśli smoke test się nie powiedzie.

Stack można usunąć tylko wtedy, gdy jest pusty. Zawsze najpierw usuń usługę i poczekaj na jej usunięcie, a dopiero potem usuń stack. Komenda service-wait-for zapewnia, że usługa jest uruchomiona lub usunięta przed przejściem dalej, dlatego jest właściwym narzędziem także do oczekiwania na usunięcie.

3. Wybierz rozmiar instancji

Poniższe przykłady domyślnie używają podstawowej instancji 20G dla Mercure Hub. To solidny wybór dla większości zastosowań, ale możesz go zmienić według potrzeb. Aby zobaczyć wszystkie dostępne typy instancji dla Mercure Hub, uruchom:

# Kolumna NAME pokazuje wartość do przekazania do --instance
stackhero instances-store-list --service-store=mercure-hub

4. GitHub Actions

Aby rozpocząć, zapisz poniższy kod jako .github/workflows/ci.yml. Od tej pory każdy push i pull request uruchomi testy na prawdziwej instancji Mercure Hub.

name: CI with Mercure Hub

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      STACKHERO_TOKEN: ${{ secrets.STACKHERO_TOKEN }}
      STACK_NAME: ci-mercure-hub-${{ github.run_id }}-${{ github.run_attempt }}
      INSTANCE: "20G"   # Zmień w razie potrzeby (patrz krok 3)
      REGION: europe
    steps:
      - uses: actions/checkout@v4

      - name: Instalacja Stackhero CLI i klienta
        run: |
          curl -fsSL https://www.stackhero.io/install.sh | sh
          apt-get update && apt-get install -y --no-install-recommends jq curl

      - name: Utworzenie usługi Mercure Hub
        run: |
          set -euo pipefail
          STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
          echo "STACK_ID=$STACK_ID" >> "$GITHUB_ENV"
          SERVICE_ID=$(stackhero --format=script service-add \
            --stack="$STACK_ID" \
            --service-store="mercure-hub" \
            --instance="$INSTANCE" \
            --region="$REGION")
          echo "SERVICE_ID=$SERVICE_ID" >> "$GITHUB_ENV"
          stackhero service-wait-for --service="$SERVICE_ID"

      - name: Uruchomienie testów na Mercure Hub
        run: |
          set -euo pipefail
          config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
          host=$(echo "$config" | jq -r '.configuration.domain')
          # Request the hub endpoint and check it answers.
          curl -fsS -o /dev/null -w "%{http_code}" "https://$host/.well-known/mercure?topic=test" | grep -qE "^(200|400|401)$"
          echo "✅ Mercure Hub jest osiągalny z CI."
          # Możesz uruchomić własny zestaw testów z powyższymi danymi dostępowymi ...

      - name: Sprzątanie (zawsze, nawet w przypadku błędu)
        if: always()
        run: |
          if [ -n "${SERVICE_ID:-}" ]; then
            stackhero service-delete --service="$SERVICE_ID" --confirm
            stackhero service-wait-for --service="$SERVICE_ID"
          fi
          if [ -n "${STACK_ID:-}" ]; then
            stackhero stack-delete --stack="$STACK_ID" --confirm
          fi

Krok sprzątania skonfigurowany jest z if: always(), dzięki czemu uruchamia się zawsze, niezależnie od wyniku, zapewniając usunięcie instancji Mercure Hub i brak naliczania opłat za nieużywane zasoby.

5. GitLab CI

Tę konfigurację możesz zapisać jako .gitlab-ci.yml. Dzięki temu każde uruchomienie pipeline'u utworzy nową, rzeczywistą instancję Mercure Hub do testów.

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-mercure-hub-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "20G"   # Zmień w razie potrzeby (patrz krok 3)
    REGION: "europe"
    SERVICE_STORE: "mercure-hub"
  # STACKHERO_TOKEN pochodzi z utworzonej w kroku 1 zmiennej CI/CD.
  script:
    - set -euo pipefail
    - curl -fsSL https://www.stackhero.io/install.sh | sh
    - apt-get update && apt-get install -y --no-install-recommends jq curl
    - STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
    - echo "STACK_ID=$STACK_ID" >> deploy.env
    - SERVICE_ID=$(stackhero --format=script service-add --stack="$STACK_ID" --service-store="$SERVICE_STORE" --instance="$INSTANCE" --region="$REGION")
    - echo "SERVICE_ID=$SERVICE_ID" >> deploy.env
    - stackhero service-wait-for --service="$SERVICE_ID"
    - config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
    - host=$(echo "$config" | jq -r '.configuration.domain')
    # Request the hub endpoint and check it answers.
    - curl -fsS -o /dev/null -w "%{http_code}" "https://$host/.well-known/mercure?topic=test" | grep -qE "^(200|400|401)$"
    - echo "✅ Mercure Hub jest osiągalny z CI."
    # Możesz uruchomić własny zestaw testów z powyższymi danymi dostępowymi ...
  after_script:
    - test -f deploy.env && . ./deploy.env || true
    - >
      if [ -n "${SERVICE_ID:-}" ]; then
        stackhero service-delete --service="$SERVICE_ID" --confirm
        stackhero service-wait-for --service="$SERVICE_ID"
      fi
    - >
      if [ -n "${STACK_ID:-}" ]; then
        stackhero stack-delete --stack="$STACK_ID" --confirm
      fi

W GitLab sprzątanie odbywa się w sekcji after_script. Ta część wykonywana jest zawsze, nawet jeśli job zakończy się niepowodzeniem, dzięki czemu zasoby Mercure Hub są usuwane i nie ponosisz kosztów za nieużywane instancje.

W GitLab after_script uruchamiany jest w nowej powłoce. Aby to obsłużyć, skrypt zapisuje identyfikatory usługi i stacka do pliku deploy.env podczas joba i ładuje je ponownie przed sprzątaniem. Dzięki temu, nawet jeśli coś się nie powiedzie w trakcie joba, Twoje zasoby zostaną poprawnie usunięte.

To kompletny cykl CI dla Mercure Hub: utwórz stack, dodaj usługę, poczekaj, pobierz dane dostępowe, wykonaj smoke test i zawsze posprzątaj. Każde uruchomienie pipeline'u korzysta z prawdziwej, odizolowanej usługi, a po zakończeniu nie pozostają żadne działające zasoby. Więcej informacji o dostępnych poleceniach i uwierzytelnianiu nieinteraktywnym przez STACKHERO_TOKEN znajdziesz w pełnej dokumentacji CLI.