Automatyzacja Google Apps Script dla procesów WordPress, Google Search Console i Google Analytics 4.
Repozytorium jest kanonicznym źródłem projektu Apps Script. Obecna wersja produkcyjna to najnowsze wydanie.
Merge do main niczego nie wdraża. Publikacja wydania w GitHubie uruchamia workflow Deploy to Apps Script dla tego taga, a opiekun zatwierdza go w środowisku production, zanim cokolwiek zostanie wypchnięte. Ten sam workflow można też uruchomić ręcznie względem main.
appsscript.json— manifest Apps Script i zakresy OAuth.Kod.gs— wspólne punkty wejścia i integracja z Google Search Console.GA4.gs— Google Analytics 4 i automatyzacja związana z Ads.WordPress.gs— most automatyzacji REST do WordPressa.Status.gs— status importów: rekordy uruchomień w Script Properties, jednolinijkowy status w komórkach konfiguracji, arkuszIMPORT LOG, menu Dane.ImportAnomaly.gs— detektor anomalii liczby wierszy importu (profil: źródło, typ uruchomienia, liczba dni; zero wierszy po historii z danymi alarmuje także w profilu bez próbek, #281).RunMarkers.gs— znaczniki wykonań (RUNNING_*): założenie, odbiór porzuconych, wpisy w logu i adnotacja wyjątku z obsługi wyniku (#189, #221, #275).Alerts.gs— alerty e-mail w modelu incydentu (otwórz raz, cisza w trakcie, zamknij po powrocie do normy) i codzienny strażnik aktualności.UrlInspection.gs— stan indeksowania kluczowych adresów z API inspekcji URL Search Console, zapisywany do arkuszaURL INSPEKCJA.SeoLive.gs— live SEO regression check: pobiera kluczowe adresy i porównuje status, cel przekierowania, title, H1, canonical, robots i schema z oczekiwaniami z arkuszaSEO LIVE.Sitemaps.gs— stan map witryny z API Sitemaps w Search Console, zapisywany do arkuszaSITEMAPYi podsumowany w Status danych.SitemapUrls.gs— adresy wyczytane z XML sitemap do arkuszaSITEMAP URLSi automatyczne dosypywanie brakujących adresów doSEO LIVEorazURL INSPEKCJA.RecrawlQueue.gs— kolejka stron, które Google powinien odwiedzić ponownie: klasyfikacja w arkuszuRECRAWL QUEUEi e-mail o nowych rekomendacjach.Diagnostics.gs— smoke test z menu, wyłącznie odczyt: Script Properties, zakładki, dostęp do GSC / GA4 / WordPressa, triggery, konfiguracja alertów, jedna linia raportu na krok.SheetCatalog.gs— katalog arkuszy tworzonych przez skrypt: kolory zakładek, kolejność, generowany spisSTARTi ukrywanie zakładek z danymi surowymi.Dates.gs—cachedFormatDate_: formatowanieDatez pamięcią pogetTime()dla pętli po dużych kolumnach dat (#229).Version.gs— same placeholdery; workflow deployu nadpisuje go tagiem wydania, commitem i czasem przedclasp push, a arkusz pokazuje ten tag jako menu (Szczegóły wdrożenia). Drift check ignoruje ten plik.eslint.config.js— reguły lintu z globalnymi symbolami Apps Script..claspignore— do Apps Script trafiają wyłącznie*.gsiappsscript.json.
Nie commituj poświadczeń ani sekretów API. Poświadczenia runtime należą do Script Properties w Apps Script.
Most WordPressa oczekuje obecnie właściwości:
WP_BASE_URLWP_USERNAMEWP_APP_PASSWORDWP_ALLOW_WRITESWP_REST_NAMESPACE— namespace snippetu REST specyficznego dla witryny, np.acmedla/wp-json/acme/v1/seo-meta.
Opcjonalne:
SITE_DOMAIN— domena używana do automatycznego wyboru właściwości GA4 po URL-u strumienia web. Fallbackiem jest host zWP_BASE_URL; bez obu właściwość trzeba wskazać ręcznie w arkuszu konfiguracji.ALERT_EMAIL— adresat alertów importu (jeden adres albo lista po przecinku). Bez niego nic nie jest wysyłane i nic nie pada; incydenty są nadal śledzone i widoczne w Status danych. Wartość, która nie jest adresem (na przykładTRUE), nigdy nie zostanie użyta: Status danych i okno strażnika pokazują ją jakoNIEPRAWIDŁOWY ADRES, dopóki nie zostanie poprawiona.ALERT_RECOVERY—FALSEwyłącza e-mail „import ponownie działa”; incydent i tak jest zamykany. Domyślnie włączone.RECRAWL_STALE_DAYS— po ilu dniach od zmiany strona bez nowego crawla trafia do rekomendacji ręcznego zgłoszenia. Domyślnie 7.EXPECTED_SITEMAPS— lista adresów sitemap po przecinku, których brak w Search Console ma być zgłaszany.GSC_KL_ANCHOR_FORMULAS— zatwierdzone formuły kolumn K i L zakładkiGSC RAW(JSON{"K": "…", "L": "…"}). Dopiero z nimi import dzienny zapisuje same importowane dni zamiast całej zakładki; zob. Import dzienny GSC niżej. Bez niej import działa jak dawniej.
WP_ALLOW_WRITES powinno pozostać wyłączone, chyba że celowo wykonujesz operację zapisu.
UPDATE_RANK_MATH_FIELD obsługuje rank_math_title, rank_math_description i rank_math_robots. Dwa pierwsze idą przez most seo-meta, robots przez endpoint seo-robots ze snippetu wordpress/page-layout-rest-bridge.php (wersja 1.1.0 i nowsza). Wartość robots wpisuje się jako listę po przecinku, na przykład noindex,follow; pusta wartość przywraca domyślne ustawienia Rank Math.
Po zapisie robots skrypt nie poprzestaje na odczycie post meta: pobiera publiczną stronę i sprawdza, co naprawdę serwuje w meta robots. Produkcja pokazała, że sam wpis w bazie nie wystarcza; polecenie kończyło się sukcesem, meta było poprawne, a strona nadal oddawała index. Porównywane są wyłącznie decyzje o indeksowaniu i podążaniu za linkami, bo Rank Math dokłada własne dyrektywy, których nie ustawiamy. Rozjazd kończy się błędem wskazującym najczęstszą przyczynę, czyli pamięć podręczną strony albo CDN, których zapis przez REST nie unieważnia. Szkic i strona, której nie udało się pobrać, nie są sprawdzane, a polecenie mówi o tym wprost zamiast udawać potwierdzenie.
Dozwolone dyrektywy: index, noindex, follow, nofollow, noarchive, noimageindex, nosnippet. Cokolwiek innego, a także pary sprzeczne (index z noindex, follow z nofollow), są odrzucane po stronie skryptu, zanim powstanie snapshot i zanim jakiekolwiek żądanie opuści Apps Script. Zapis przechodzi normalną ścieżką: snapshot przed zmianą, odczyt kontrolny po zmianie (kolejność dyrektyw nie ma znaczenia), możliwość cofnięcia przez RESTORE_SNAPSHOT. Na instalacji ze starszym snippetem komenda odmawia z komunikatem wskazującym plik do aktualizacji, a WordPress → Test Rank Math bridge pokazuje brak obsługi robots.
Źródła Apps Script mieszkają w src/: pliki *.gs plus appsscript.json. Katalog główny trzyma wyłącznie konfigurację narzędzi, dokumentację i licencję.
Apps Script nie ma katalogów, więc clasp dostaje rootDir wskazujący src. Dzięki temu nazwy plików po stronie Google są dokładnie takie jak wcześniej, bez prefiksu katalogu. Workflow deployu i drift check wykrywają układ same: wdrożenie taga sprzed tej zmiany, czyli rollback, nadal działa, bo wtedy rootDir wskazuje katalog główny.
WP_ALLOW_WRITES to jedyny wyłącznik chroniący produkcyjny WordPress przed niezamierzonym zapisem. W praktyce zostaje włączony na stałe, bo tak jest wygodniej przy częstych zmianach, a wyłącznik zawsze włączony nie chroni przed niczym. WP_DRY_RUN daje problem odwrotny: zapomniany sprawia, że komendy tylko udają zapis.
Status danych pokazuje więc obie flagi wraz z czasem, przez jaki są w tym stanie, a po tygodniu dokłada ostrzeżenie nazywające problem. Moment włączenia jest odnotowywany przy okazji uruchomień, które i tak zapisują: codziennego strażnika alertów oraz otwarcia okna statusu. Wyłączenie flagi kasuje znacznik, więc ponowne włączenie liczy się od nowa.
Nic nie zmienia wartości flagi automatycznie. Flaga gasnąca sama w losowym momencie zamieniłaby przewidywalny system w taki, który odmawia zapisu w środku pracy.
Repozytorium jest publiczne, więc slug strony ze źródłem stopki, identyfikator bloku stylów i klasa stopki nie są zaszyte w kodzie. Migracja stopki czyta je ze Script Properties WP_GLOBAL_FOOTER_SOURCE_SLUG, WP_GLOBAL_FOOTER_STYLE_ID i WP_GLOBAL_FOOTER_CLASS. Brak którejkolwiek kończy się jasnym błędem, a nie cichym podstawieniem. Dozwolone są wyłącznie małe litery, cyfry i myślnik, dzięki czemu wartość jest bezpieczna zarówno w wyrażeniu regularnym, jak i we wstrzykiwanym kodzie PHP.
Pole REST z robots nazywa się wpa_rank_math_robots — spójnie z prefiksem funkcji w moście. Nazwa historyczna, pochodząca od skrótu nazwy firmy, została usunięta po tym, jak instalacja potwierdziła wystawianie docelowej (#103). WordPress → Test Rank Math bridge mówi, czy Twoja instalacja wystawia to pole; snippet starszy niż #103 wygląda z punktu widzenia skryptu jak brak pola i wymaga podmiany.
Arkusz Google ma twardy limit 10 mln komórek na cały plik, dzielony przez wszystkie zakładki. Po jego przekroczeniu przestaje działać nie jedna funkcja, tylko wszystko naraz: importy, monitoring i komendy. Dane → Zajętość arkusza pokazuje procent limitu i największe zakładki, a linia ze stanem jest też w Status danych.
Rosną tylko trzy zakładki dopisywane wierszami. IMPORT LOG ma własną retencję 90 dni. WP RESULTS i WP SNAPSHOTS czyści Dane → Wyczyść stare snapshoty i wyniki.
Czyszczenie nie jest automatyczne i nie ma triggera. Snapshot jest siatką bezpieczeństwa dla rollbacku, a jego skasowanie jest nieodwracalne, więc usuwa je wyłącznie człowiek, po zobaczeniu w dialogu dokładnej liczby wierszy. Snapshot młodszy niż 30 dni zostaje zawsze, podobnie pięć najnowszych na każdą stronę; wiersz bez czytelnej daty jest traktowany jak świeży. Wyniki starsze niż 180 dni są usuwane, bo są wyłącznie informacyjne.
Retencja surowych prób PSI (#152). PAGESPEED LAB trzyma jeden wiersz na (pomiar, adres, strategię, próbę, metrykę), więc rośnie najszybciej ze wszystkich zakładek. Dane → Wyczyść stare snapshoty, wyniki i próby PSI zostawia osiem najnowszych pomiarów — dwie doby przy cyklu co 6 godz., dość, żeby podejrzany przebieg porównać z sąsiednimi. Starszy pomiar wolno usunąć dopiero wtedy, gdy dla tego samego znacznika istnieją mediany w PERFORMANCE SUMMARY dla każdej pary (adres, strategia), która miała udaną próbę; inaczej surowe próby są jedynym nośnikiem wyniku i zostają mimo wieku. Dialog podaje, ile pomiarów zablokowano z tego powodu — bez tej liczby „usunięto zero” nie odróżnia działającej polityki od zepsutej. PERFORMANCE SUMMARY nie podlega tej retencji: to trwała historia baseline’ów.
Znacznik Pomiar jest tekstem, nie datą (#168). Trzy zakładki PSI — PAGESPEED LAB, PAGESPEED FINDINGS i PERFORMANCE SUMMARY — łączy klucz (Pomiar, URL, Strategia, Próba), a Arkusze parsują zapisany łańcuch 2026-09-13 13:14:11 na wartość daty. Nie chodzi przy tym o sam wygląd: format, który kolumna już ma, obcina to, co zostaje zapisane. Zmierzone na produkcji 2026-09-14, po migracji: wszystkie 52 z 52 znaczniki w PAGESPEED LAB miały sekundy 00, choć PERFORMANCE SUMMARY trzymało dla czterech z tych samych przebiegów 13:14:11, 16:46:24, 18:25:28 i 00:25:29. Jeden przebieg zapisuje jeden łańcuch do obu zakładek w sąsiednich liniach kodu, więc różnicę zrobił arkusz — kolumna w LAB niosła format minutowy sprzed #156, a SUMMARY powstało później i miało automatyczny. W komórce LAB sekund już nie było — nie ukrywał ich format, zniknęły z wartości. Trzeba jednak rozróżnić dwa przypadki. Przebiegi sprzed #156 niczego nie straciły: znacznik był wtedy generowany z dokładnością do minuty, więc :00 jest wiernym zapisem. Cztery przebiegi po #156 straciły sekundy tylko w LAB: PERFORMANCE SUMMARY zachowało je dokładnie, a w każdej z tych minut był jeden przebieg, więc dopasowanie było jednoznaczne. 2026-09-16 znaczniki tych czterech przebiegów przywrócono w LAB na podstawie SUMMARY (192 wiersze); od tej chwili każdy znacznik z SUMMARY ma parę w LAB. Bez tego retencja surowych prób blokowałaby je na zawsze, bo nie znalazłaby dla nich median. Kolumna Pomiar dostaje dlatego format tekstowy ustawiany przed zapisem, a wartości postać RRRR-MM-DD GG:MM:SS liczoną w strefie arkusza (Plik → Ustawienia), nie w strefie skryptu — komórka z datą to północ w strefie arkusza i tylko ta strefa odwraca to, co arkusz zrobił przy zapisie. CWV FIELD zostaje przy dobie RRRR-MM-DD, bo Okres do to okno CrUX, a nie chwila.
Historię zapisaną wcześniej przepisuje jednorazowa komenda Dane → Kanonizuj znaczniki Pomiar: dialog podaje, ile wierszy w której zakładce zostanie przepisanych, zanim cokolwiek ruszy, całość idzie pod tą samą blokadą co pomiar, a stan zapisuje się per zakładka i jest widoczny w Status danych. Przerwanie w połowie zostawia zakładkę nieoznaczoną, więc kolejne uruchomienie ją powtórzy; powtórzenie jest bezpieczne, bo wartość już kanoniczna nie jest ruszana. Migracja zmienia wyłącznie postać zapisu — żadnej chwili, żadnej innej kolumny, żadnej kolejności wierszy.
SEO LIVE, URL INSPEKCJA i RECRAWL QUEUE mają jeden wiersz na adres, aktualizowany w miejscu. Rosną więc razem z serwisem i retencji nie potrzebują.
Osobnym i zwykle większym problemem jest pusty przydział. Google liczy do limitu całą siatkę, nie wypełnione komórki, więc zakładka z kilkoma tysiącami wierszy danych rozciągnięta na sto tysięcy wierszy zajmuje kilkanaście razy więcej, niż powinna. Dane → Przytnij puste wiersze usuwa wyłącznie wiersze poniżej ostatniego wypełnionego, zostawiając dwa tysiące wolnych na zapas, i pokazuje przed usunięciem, co dokładnie zniknie. Przed pytaniem narzędzie skanuje formuły we wszystkich zakładkach i wypisuje te, które odwołują się do usuwanego obszaru numerem wiersza, na przykład 'GSC RAW'!F2:F100000. To cicha pułapka: Arkusze przepiszą taki zakres po usunięciu wierszy i nic od razu nie pęknie, ale gdy zakładka znowu urośnie ponad nową granicę, nowe dane wypadną poza zakres i przestaną być liczone, bez błędu i bez sygnału. Zakresy otwarte (F2:F) są bezpieczne i nie są zgłaszane.
Granica jest wyznaczana przez skan wartości i formuł od dołu, a nie przez getLastRow(): ten zwraca koniec zakresu danych arkusza, który bywa zawyżony przez samo formatowanie po dawnych importach. Formuła licząca się do pustego tekstu też jest treścią i nie zostanie usunięta. Żadna dana przy tym nie ginie, ale formuła odwołująca się wprost do komórki z usuwanego zakresu pokaże potem #REF!, i dialog o tym uprzedza.
Wszystkie zadania cykliczne, nie tylko importy GSC i GA4, zapisują czas ostatniego udanego przebiegu i podlegają temu samemu modelowi incydentów: jeden e-mail przy otwarciu, cisza w trakcie, e-mail przy powrocie do normy. Bez tego zadanie, które przestało działać, byłoby nieodróżnialne od zadania, które nie ma nic do zgłoszenia, bo kolejka recrawl i live check SEO piszą maila tylko wtedy, gdy coś znajdą.
Próg nieaktualności jest ustawiany per zadanie: doba z okładem dla zadań codziennych, osiem dni dla tygodniowych. Dane → Status danych pokazuje każde zadanie z jego harmonogramem, progiem i ostatnim uruchomieniem.
Trzy sytuacje są rozróżniane, bo każda znaczy co innego. Zadanie monitorujące bez zainstalowanego triggera, które nigdy nie działało, jest nieużywane, a nie zepsute, i milczy. Zadanie z triggerem, które jeszcze nie zapisało przebiegu, dostaje swój własny próg na pierwsze uruchomienie: tak wygląda instalacja tuż po włączeniu monitoringu, gdzie trigger jest od dawna, a znacznik dopiero się pojawił. Dopiero gdy próg minie bez ani jednego przebiegu, otwiera się incydent. Brak importu jest zgłaszany zawsze, bo import jest zawsze oczekiwany. Drugi wyjątek to sam strażnik alertów: gdyby stanął, nie miałby jak zgłosić własnej awarii, więc wykrywa go diagnostyka sprawdzająca zainstalowane triggery.
Przebieg ubity limitem wykonania nie znika bez śladu (#189). Apps Script kończy wykonanie po 6 minutach twardo: nie wykonuje się ani catch, ani finally, więc taki przebieg nie zostawiał rekordu, wiersza w IMPORT LOG ani maila — 19.09.2026 przebieg pomiaru wydajności był widoczny wyłącznie w rejestrze wykonań Apps Script. Każde wykonanie zadania cyklicznego zakłada więc przed pracą znacznik — osobną Script Property RUNNING_<zadanie>_<runId> — i usuwa go po kontrolowanym zakończeniu, udanym czy nieudanym. Osobną właściwość, a nie pole rekordu zadania, bo rekord zapisuje też obsługa incydentów ze swojej kopii i znacznik ginąłby przy nakładających się wykonaniach. Znacznik starszy niż 7 minut, zastany przy kolejnym starcie, znaczy, że poprzednie wykonanie nie dotarło do żadnego zakończenia: przebieg dopisuje za nie wiersz BŁĄD do IMPORT LOG — z czasem startu i pustym czasem trwania, bo chwili ubicia nie znamy — i sam kończy się ostrzeżeniem z mailem „UWAGA”. Wiersz powstaje dla każdego zadania, także takiego, które zwykłych przebiegów do IMPORT LOG nie zapisuje: nota w ostatnim przebiegu znika przy kolejnym, więc nie jest trwałym śladem (#221). Znacznik porzuconego schodzi dopiero po zapisie wiersza. Gdy zapis się nie uda, znacznik czeka na kolejny przebieg, a bieżący robi swoją pracę. Po awarii odzysku ten sam porzucony przebieg może więc mieć w IMPORT LOG dwa wiersze — duplikat zamiast utraconego śladu. Treść nie przesądza ani przyczyny, ani tego, co zdążyło się zapisać: dane zapisują się w trakcie przebiegu. Znaczniki młodsze niż 7 minut mogą należeć do wykonania, które wciąż trwa, i nie są ruszane. RUNNING_… w Script Properties to normalny widok w trakcie przebiegu; nie usuwaj ich ręcznie, bo ubity przebieg przeszedłby wtedy bez śladu.
To samo dotyczy importów GSC i GA4 (#209). 27.09.2026 limit ubił codzienny import GSC i nie został żaden ślad poza rejestrem wykonań. Import zakłada teraz taki sam znacznik. Porzucony znacznik importu odbiera następny przebieg tego źródła albo, wcześniej, codzienny strażnik ok. 08:00. Następny przebieg dopisuje wiersz BŁĄD, a sam kończy się ostrzeżeniem z mailem „UWAGA”. Strażnik dopisuje wiersz BŁĄD, ustawia porzucony przebieg jako ostatni (komórka statusu pokazuje BŁĄD) i otwiera incydent z mailem „BŁĄD importu”, więc import ubity o 05:13 jest zgłoszony tego samego ranka, a nie po dobie. Nowszego przebiegu, np. ręcznego importu po ubitym, strażnik nie nadpisuje i zostawia tylko wiersz w logu. Znacznik schodzi u strażnika dopiero po incydencie (#221). Awaria w trakcie odzysku zostawia go na następny przebieg strażnika, który dopisze drugi wiersz; drugi mail wyjdzie tylko wtedy, gdy wykonanie ubito między wysyłką maila a zapisem, że wyszedł.
Wyjątek w obsłudze wyniku nie udaje limitu czasu (#275). Rejestratory przebiegów osłaniają try/catch samą pracę, a skutki udanej pracy (rekord, wiersz IMPORT LOG, status, incydent) idą pod osobną osłoną: wyjątek stamtąd leci dalej bez zmian, ale własny znacznik RUNNING_<zadanie>_<runId> (tylko ten, pozostałe pola bez zmian) dostaje pole failure z przyczyną. Znacznik nadal nie schodzi - to siatka bezpieczeństwa z #214 i #221. Odbiór takiego znacznika mówi „obsługa wyniku przerwana wyjątkiem: ; praca zakończona” zamiast domysłu o limicie. Przyczyna to wyłącznie message, w jednej linii, po redakcji (nagłówek Bearer, pary typu token=..., adresy e-mail, zapytanie adresu URL i każdy ciąg 24 i więcej znaków [A-Za-z0-9_-] zastępuje [ukryto]), najwyżej 200 znaków. Wartość pary w cudzysłowie albo apostrofach jest czytana ze świadomością ucieczek: \" i \\ wewnątrz wartości jej nie kończą (JSON z " w haśle, także JSON zagnieżdżony w napisie, gdzie ogranicznikiem jest dokładnie jeden ukośnik przed cudzysłowem), więc wartość znika w całości, a niedomknięta jest redagowana do separatora; pusta daje nieznany wyjątek. Gdy zapis adnotacji zawiedzie, znacznik zostaje bez niej, a odbiór używa ostrożnego tekstu („możliwe przerwanie przez limit czasu”) - limit czasu nie jest nigdy podawany jako fakt. Wyjątek z samej pracy (fn()) idzie dotychczasową ścieżką: znacznik schodzi, rekord ma ok: false.
SEO / GSC → Przygotuj pomiar wydajności zakłada cztery zakładki: PERFORMANCE URLS z listą monitorowanych adresów, CWV FIELD z danymi terenowymi, PAGESPEED LAB z pomiarami laboratoryjnymi i PAGESPEED FINDINGS z diagnozą. Zmierz wydajność uruchamia oba pomiary.
Potrzebny jest klucz API z Google Cloud, w Script Property PAGESPEED_API_KEY, z włączonymi PageSpeed Insights API oraz Chrome UX Report API. Obie usługi działają na klucz w parametrze zapytania, bez OAuth, więc włączenie tej funkcji nie wymaga ponownej autoryzacji projektu.
Dane terenowe i laboratoryjne są trzymane osobno i nigdy nie uśredniane w jedną liczbę. CrUX pokazuje, co przeżyli prawdziwi użytkownicy, PSI to jeden przebieg Lighthouse na maszynie Google. Zlepienie ich dałoby wskaźnik, który nie znaczy nic.
Pojedyncza podstrona rzadko ma dość ruchu, żeby CrUX ją opisał, a cała domena zwykle ma. Gdy adres wraca bez danych, pytamy więc o całą domenę i zapisujemy wynik ze źródłem CRUX (domena). To rozróżnienie jest istotne: liczba opisuje wtedy serwis, a nie tę stronę, i nie wolno jej czytać jako pomiaru konkretnego adresu. O domenę pytamy raz na form factor, a nie raz na adres.
Dwie decyzje wpływające na wiarygodność. Brak danych terenowych jest zapisywany jako INSUFFICIENT_DATA, nigdy jako zero: zero znaczyłoby wynik doskonały, czyli dokładną odwrotność prawdy. Pomiar laboratoryjny wykonuje trzy próby na adres i strategię, zapisuje każdą osobno i porównuje przez medianę, bo Lighthouse jest zmienny i pojedynczy słaby wynik nie jest dowodem regresji.
O tym, czy nieudana próba Lighthouse jest szumem, decyduje wynik całego zakresu, a nie kod błędu (#179). Zakres to para adres × strategia i ma trzy stany: OK (trzy udane próby z trzech), OSTRZEŻENIE (jedna albo dwie — wynik zostaje, ale stoi na słabszej podstawie i widać to w opisie przebiegu) oraz NIEUDANY (zero udanych). Zakres NIEUDANY nie dostaje nowych wierszy ani mediany, a jego ostatnia dobra diagnoza w PAGESPEED FINDINGS zostaje nietknięta. Odpowiedź, w której nie ma ani jednej wartości, też jest nieudaną próbą: pomiar bez liczb nie jest pomiarem.
Przebieg kończy się błędem tylko wtedy, gdy żaden z rozpoczętych zakresów nie dał danych. Gdy część dała, zadanie kończy się poprawnie, a nieudane zakresy idą mailem „UWAGA”; martwy adres nie blokuje więc ani zapisu pozostałych, ani rotacji kursora. Natychmiast przerywają wyłącznie błędy konfiguracji i limitu (403 i 429), bo kolejne próby dałyby to samo. Każdy przebieg cykliczny zostawia wiersz w IMPORT LOG z wynikiem OK, UWAGA albo BŁĄD — bez tego kolejne awarie przy otwartym incydencie znikałyby bez śladu.
Alert podaje adres, strategię, liczbę nieudanych prób i rodzaj błędu, na przykład HTTP 400 FAILED_DOCUMENT_REQUEST (net::ERR_TIMED_OUT) ×3, i nie przesądza przyczyny. „PSI nie zdołał zmierzyć adresu” to fakt; czy zawiodła strona, sieć, czy sam PSI, rozstrzygają inne dane. 14–15.09.2026 ten błąd pojawiał się, gdy domena była za CDN, a ręczny PageSpeed też nie mógł wtedy sprawdzić strony, i zniknął po powrocie do pierwotnego DNS.
Awaria CrUX nie zabiera danych PSI (#187). To dwa niezależne źródła i dwa osobne API Google, włączane osobno dla tego samego klucza, więc błąd jednego — przejściowy czy konfiguracyjny — nie może zatrzymać drugiego. 17.09.2026 jeden 503 z CrUX zabił trzy przebiegi, zanim PSI wysłał choćby jedno żądanie, bo CrUX idzie pierwszy. Żądanie CrUX zakończone błędem 5xx albo wyjątkiem transportowym dostaje jedno ponowienie; 400 i pozostałe 4xx nie dostają żadnego, bo identyczne żądanie dałoby to samo, a 404 znaczy jak dotąd „za mało danych”. Para adres × form factor, której żądanie się nie udało, nie jest parą bez danych: nie dostaje wiersza INSUFFICIENT_DATA, bo ten jest twierdzeniem o ruchu na stronie, a jej poprzedni wiersz zostaje nietknięty. Pary pobrane przed awarią trafiają do CWV FIELD w każdym przypadku. 403 i 429 kończą tylko żądania CrUX: PSI i tak się wykonuje i zapisuje, a zadanie kończy się błędem, bo taki stan sam nie minie — z treścią, która mówi, co mimo to zapisano. Nieudane pary dają mail „UWAGA”; gdy zawiodą oba źródła naraz, przebieg zgłasza jeden błąd opisujący oba. Opis przebiegu i IMPORT LOG pokazują licznik w tym samym kształcie co zakresy PSI: pary: OK 6 | bez danych 2 | nieudane 2. Klucz API jedzie w adresie żądania, a komunikat wyjątku potrafi ten adres zacytować, więc w rodzaju błędu klucz jest zamaskowany (key=…), zanim trafi do logu albo maila.
Pomiar laboratoryjny ma budżet czasu. Jedno wywołanie PSI trwa kilkanaście do kilkudziesięciu sekund, a przy trzech próbach i dwóch strategiach daje sześć wywołań na adres, więc kilka adresów przekroczyłoby limit czasu wykonania Apps Script. Przebieg mierzy tyle adresów, ile mieści się w budżecie czterech minut, i zapamiętuje, gdzie skończył; kolejny zaczyna od następnego adresu. Przy cyklicznym uruchamianiu wszystkie doczekają się pomiaru, a komunikat mówi, ile zostało na później. Budżet jest sprawdzany przed rozpoczęciem adresu, nie w trakcie, bo mediana z dwóch prób zamiast trzech jest gorsza niż jej brak. Nie chroni on jednak przed limitem wykonania Apps Script: rozpoczęty adres to sześć żądań po kolei, a nocą jeden adres potrafi zająć blisko 300 z 360 dostępnych sekund — 19.09.2026 przebieg został w ten sposób ubity. Naprawa (wspólny termin dla CrUX i PSI, zakres zamiast adresu jako jednostka pracy) czeka w etapie 2 #189 na dane: każde żądanie CrUX i PSI zapisuje w logach Cloud rejestru wykonań linię [czas żądania] źródło | zakres | próba | czas | wynik, bez adresu endpointu i bez klucza.
Zapis jest idempotentny: ponowny pomiar tego samego okresu CrUX podmienia wiersze zamiast je dublować, a historia wcześniejszych okresów zostaje.
Cykliczny pomiar i dzienny budżet wywołań. Włącz cykliczny pomiar wydajności zakłada wyzwalacz uruchamiający CrUX i PSI razem. Dwie opcjonalne Script Properties:
PAGESPEED_INTERVAL_HOURS— co ile godzin; dozwolone są wyłącznie wartości przyjmowane przez wyzwalacz czasowy Apps Script:1,2,4,6,8,12. Brak albo inna wartość oznacza6. Po zmianie trzeba ponownie uruchomić Włącz cykliczny pomiar wydajności — wyzwalacz nie czyta tej właściwości sam.PAGESPEED_DAILY_BUDGET— ile wywołań PSI wolno wykonać w ciągu doby liczonej w strefie arkusza; domyślnie500, wartość niedodatnia albo nieczytelna też oznacza500. To nasz licznik, nie limit Google: chroni przed zużyciem cudzego limitu, ale go nie odczytuje. Budżet jest rezerwowany na cały adres (sześć wywołań) przed jego rozpoczęciem, więc adres nigdy nie zostaje zmierzony w połowie. Licznik liczy wywołania rozpoczęte: zapisuje się przed każdym z nich, a nie po nim, więc wykonanie ubite w trakcie żądania zawyży go najwyżej o jedno, ale nigdy nie zaniży (#189). Stan licznika trzymaPAGESPEED_BUDGET_STATE— nie edytuj go ręcznie.
Adres do monitorowania dodaje się wierszem w PERFORMANCE URLS. Musi zaczynać się od http:// albo https:// — wiersz z czymkolwiek innym w kolumnie URL jest pomijany bez komunikatu. Kolumna Rola jest zwykłym tekstem dla człowieka i nie zmienia sposobu pomiaru.
Same metryki mówią, że strona jest wolna, ale nie dlaczego. Odpowiedź PSI zawiera już diagnozę, więc obok liczb zapisujemy trzy rodzaje ustaleń: ELEMENT LCP (selektor albo fragment elementu, który wyznacza LCP), SZANSA (audyty typu opportunity z szacowaną oszczędnością) oraz THIRD-PARTY (transfer i czas wątku głównego na podmiot).
Koszt i potencjalna oszczędność mają osobne kolumny. Czas (ms) i Transfer (KiB) opisują to, co strona realnie zużywa; Potencjalna oszczędność (ms) i Potencjalna oszczędność (KiB) to, co da się odzyskać. Jednostką jest KiB, czyli 1024 bajty — tak samo jak w raporcie PageSpeed, żeby liczby dało się porównywać wprost. Podsumowanie third-party trafia wyłącznie do kolumn kosztu — wpisanie go do oszczędności sprawiłoby, że arkusz kłamałby semantycznie.
To jest snapshot bieżącej diagnozy, nie historia. Udany pomiar zastępuje cały zakres (URL, strategia), więc ustalenie, którego nie ma w nowej odpowiedzi, znika z arkusza. Zwykły upsert zostawiłby nieaktualne szanse jako obowiązującą diagnozę. Historia liczb jest w PAGESPEED LAB i tam należy. Zakres bez ani jednej udanej próby nie jest ruszany: nieudany przebieg nie kasuje ostatniej dobrej diagnozy.
Ustalenia pochodzą z ostatniej udanej próby, a kolumna Próba mówi z której — dzięki temu diagnozę da się połączyć z konkretnym wierszem metryki w PAGESPEED LAB. Szanse są kwalifikowane progiem (50 ms albo 20 KiB) i ograniczone do pięciu na adres i strategię, w deterministycznej kolejności; bez tego arkusz zapełniłby się pozycjami bez znaczenia praktycznego.
Import wydajności i miesięcznych fraz wyszukiwania do zakładek GBP PERFORMANCE RAW i GBP SEARCH KEYWORDS. SEO / GSC → Przygotuj Business Profile zakłada obie i mówi, czego jeszcze brakuje do uruchomienia.
Po stronie Google potrzebne są dwie rzeczy, których nie da się załatwić kodem: włączone Business Profile Performance API w projekcie Google Cloud i przyznany dostęp do rodziny Business Profile. O dostęp wnioskuje się osobno; samo włączenie API nie wystarcza, bo bez wniosku limit wynosi zero.
Zakres business.manage jest w appsscript.json. Dopisano go dopiero po przyznaniu dostępu, bo każda zmiana zakresów wymusza ponowną autoryzację całego projektu: po wdrożeniu takiej wersji pierwsze uruchomienie z menu prosi o zgodę, a do tego czasu wyzwalacze czasowe nie wykonają się poprawnie. Odmowa API kończy się komunikatem, który rozróżnia odmowę uwierzytelnienia (401), brak przyznanego dostępu (403) i złą lokalizację (404).
Dostęp dostaje projekt Google Cloud, a import używa tokenu projektu Apps Script (ScriptApp.getOAuthToken()), więc Apps Script musi korzystać ze standardowego projektu Cloud, tego samego, dla którego złożono wniosek. Ekran zgody OAuth takiego projektu musi być opublikowany (Platforma uwierzytelniania Google → Odbiorcy, stan „W wersji produkcyjnej”). W stanie „Testowanie” Google wydaje autoryzację ważną 7 dni; potem przestają startować wszystkie wyzwalacze czasowe projektu, bez błędu w rejestrze wykonań i bez maila, a razem z nimi strażnik aktualności (#198). Naprawa ma ustaloną kolejność: najpierw publikacja, dopiero potem ponowna autoryzacja, bo token wydany jeszcze w stanie „Testowanie” wygasa po 7 dniach także po publikacji. Aplikacja zostaje niezweryfikowana: przy zgodzie Google pokazuje ostrzeżenie, a limit takiej aplikacji to 100 użytkowników.
Codzienny import włącza SEO / GSC → Włącz codzienny import Business Profile. Trigger startuje ok. 11:00, w godzinie, w której nie startuje żadne inne zadanie. Blokada skryptu czeka tylko 5 s, a na przykład w poniedziałek o 07:00 inspekcja URL wysyła do 150 zapytań. Test pilnuje, żeby żaden trigger o stałej godzinie nie trafił w tę samą godzinę. Pobiera metryki z ostatnich 7 dni, a nie tylko wczorajsze, bo Google uzupełnia wartości kilka dni wstecz: 26.09.2026 połączenia za 22.09 dostały wartość między dwoma importami tego samego dnia. Frazy dotyczą ostatniego pełnego miesiąca. Zadanie jest w rejestrze zadań cyklicznych jako opcjonalne (GBP), więc brak udanego przebiegu przez 36 h zgłasza strażnik, diagnostyka pokazuje trigger, a każdy przebieg zostawia wiersz w IMPORT LOG. Tydzień bez żadnego pomiaru kończy przebieg ostrzeżeniem z mailem „UWAGA”, a nie błędem: import się udał, ale to więcej niż zwykłe, 2–3-dniowe opóźnienie Google. Bez GBP_LOCATION pozycja menu odmawia założenia triggera. Import z menu idzie pod tą samą blokadą skryptu, bo upsert przepisuje całą zakładkę, i nie zapisuje rekordu zadania, tak jak ręczny live check SEO.
Lokalizacja pochodzi ze Script Property GBP_LOCATION w formacie locations/<id>, więc identyfikator instalacji nie trafia do repozytorium. Import jest idempotentny: ponowne uruchomienie tego samego zakresu podmienia wiersze zamiast je dublować, a backfill starszego okresu nie kasuje nowszych danych. Klucz porównuje dzień i miesiąc w postaci kanonicznej, bo arkusz zamienia zapisany tekst RRRR-MM-DD i RRRR-MM na daty. To ta sama pułapka co w #155; zanim ją obsłużono, każdy import dopisywał wszystko od nowa. Duplikaty, które zdążyły powstać, scala każdy kolejny import, a okno importu podaje ich liczbę.
Trzy decyzje wpływające na dane. Punkt z datą, ale bez wartości, to zero, bo tak opisuje go dokumentacja API: value „nie występuje, gdy wartość wynosi zero”. Tak samo wyglądają jednak dni, których Google jeszcze nie przetworzył, więc zero trafia tylko do horyzontu, czyli ostatniego dnia, dla którego odpowiedź ma jakąkolwiek wartość. Późniejsze dni zostają puste do kolejnego importu, a okno importu mówi, do kiedy są dane. Frazy rozróżniają wartość dokładną od progu, poniżej którego Google nie podaje liczby; potraktowanie progu jak liczby zawyżałoby sumy. Frazy dotyczą ostatniego pełnego miesiąca i wiersz dostaje miesiąc zapytania, a nie miesiąc uruchomienia: API sumuje wyświetlenia z całego zakresu monthlyRange, więc każdy miesiąc to osobne zapytanie. Na początku miesiąca dane bywają niepełne; ponowny import podmienia je dzięki upsertowi.
Zakładka ZAPYTANIA TELEFONICZNE zbiera to, co dotąd przepadało: klient dzwoni, pyta o trasę, dostaje wycenę i znika. Wypełnia ją człowiek w trakcie rozmowy albo tuż po niej, a skrypt zakłada wyłącznie strukturę. Dane → Przygotuj rejestr zapytań telefonicznych zakłada zakładkę albo przejmuje istniejącą z tym samym nagłówkiem i nie rusza wpisanych wierszy: odnawia walidacje, zamraża nagłówek i dodaje notatkę przy kolumnie Uwagi. Zakładki o tej nazwie z innym nagłówkiem nie nadpisuje, tylko wymienia w oknie różnice.
Kolumny to Data, Skąd, Dokąd, Usługa, Wycena [zł], Wynik, Skąd o nas wie i Uwagi. Listy wyboru mają Usługa, Wynik i Skąd o nas wie. Lista Usługa (miejska / podmiejska / krajowa / kurier dedykowany / inne) to ten sam słownik co w zleceniach z formularza (#195), więc oba źródła da się zestawić. Data wymaga daty, a Wycena [zł] liczby ≥ 0. Nietypowa wartość zostaje zapisana z ostrzeżeniem, a nie odrzucona, bo szybkość wpisywania w trakcie rozmowy jest ważniejsza niż wymuszanie. Poziom szybkości (Standard, Ekspres) trafia do Uwag. Walidacje obejmują wiersze istniejące w chwili uruchomienia; po dołożeniu wierszy do zakładki wystarczy uruchomić pozycję menu ponownie.
Brak dedykowanych pól kontaktowych; danych osobowych nie wpisujemy do Uwag. To rejestr popytu do analityki, a nie CRM, i do liczenia tras, cen oraz wyników dane kontaktowe nie są potrzebne. Wolny tekst może je mimo to zawierać, więc zakładka podlega tym samym zasadom przechowywania co reszta arkusza. W katalogu zakładek jest arkuszem własnym (wlasne, właściciel człowiek), dlatego Ukryj arkusze techniczne jej nie chowa.
Zakładka ZLECENIA ANALITYKA mówi, co i skąd dokąd zlecają klienci. GA4 mówi tylko, jak do zlecenia trafili. Dane pochodzą z osobnego mostu tylko do odczytu w WordPressie (snippet Code Snippets), który dla każdego zgłoszenia formularza zleceń wydaje wyłącznie pola z allowlisty, zminimalizowane już w PHP:
Nr— identyfikator zgłoszenia;Data— sama data, z surowego zapisu zgłoszenia (date_created_sql). Poletime_createdForminatora to tekst do wyświetlania, np. „maj 16, 2026 @ 1:58 AM”, i nie nadaje się do porównań;Usługa— grupa:miejska/podmiejska/krajowa/kurier dedykowany, ten sam słownik co w rejestrze zapytań telefonicznych;Wariant usługi— początek etykiety wybranej opcji do pierwszej półpauzy, np. „Standard”, „Ekspres 12”. Zawsze jest to jedna z bieżących opcji pola, więc wartość spoza nich daje pustą komórkę, a nie wolny tekst. Forminator zapisuje pod kluczem pola wyboru etykietę opcji, a wysłaną wartość trzyma osobno w_forminator_choice_values. Most dopasowuje najpierw wysłaną wartość, a potem etykietę: to obsługuje starsze zgłoszenia i opcje, którym po zgłoszeniu zmieniono opis po półpauzie. Okno importu podaje, ile wierszy z usługą nie ma rozpoznanego wariantu. Gdy nie ma go żaden, okno ostrzega o błędzie mostu. Tak objawił się pierwszy import 26.09: wariant był pusty w 334 z 334 wierszy, bo most szukał etykiety po wartości;SkądiDokąd— miejscowość: tylko litery, spacje i łącznik, najwyżej 40 znaków, inna wartość daje pustą komórkę;Skąd (region)iDokąd (region)— dwie pierwsze cyfry kodu pocztowego;Strona wysłania— sama ścieżka adresu, bez parametrów.
Czego świadomie nie ma: imienia i nazwiska, telefonu, e-maila, firmy, ulicy, pełnego kodu pocztowego ani uwag. Żaden klucz wyjściowy nie dopuszcza ich typu pola ani podpola. Mapowanie działa fail-closed. Script Properties wskazują tylko, które pole zasila który klucz (WP_ORDER_FORM_ID, WP_ORDER_SERVICE_FIELDS w postaci radio-1:miejska, radio-5:podmiejska…, WP_ORDER_FROM_FIELD, WP_ORDER_TO_FIELD, opcjonalnie WP_ORDER_SOURCE_FIELD). Przedrostek klucza pola jest sprawdzany przy przygotowaniu snippetu, a typ pola w schemacie formularza — w PHP przy każdym wywołaniu. Pole innego typu albo nieobecne w formularzu daje błąd bez wierszy. Import ma drugą, niezależną warstwę tej samej kontroli: klucz spoza allowlisty w odpowiedzi przerywa import bez zmiany zakładki, a wartość o złym kształcie staje się pustą komórką.
To dane osobowe pseudonimizowane, a nie anonimowe. Nr łączy wiersz ze zgłoszeniem w WordPressie (niesie idempotencję), a miejscowość jest wolnym tekstem, więc słowo bez cyfr, np. sama nazwa ulicy, przejdzie normalizację. Dlatego obowiązuje retencja 24 miesiące w kodzie, a cel analityczny musi być w polityce prywatności przed pierwszym importem na produkcji. Import jest pełną synchronizacją: zakładka odzwierciedla bieżące zgłoszenia w granicach retencji. Zgłoszenie usunięte w WordPressie, np. na żądanie klienta, znika z zakładki przy następnym imporcie, a ponowny import niczego nie dubluje. Regiony są zapisywane jako tekst, żeby „05” nie stało się liczbą 5.
Instalacja idzie tą samą ścieżką zatwierdzania zapisu co most historii B2B. Wymaga WP_ALLOW_WRITES=TRUE i jednorazowego uzbrojenia przed każdą operacją zapisu, gdy uruchamiasz z edytora. Kolejne kroki: armOrderAnalyticsWrite(), prepareOrderAnalyticsBridge() (tworzy nieaktywny snippet), ponownie armOrderAnalyticsWrite(), activateOrderAnalyticsBridge(), a na koniec auditOrderAnalyticsBridge(). Audyt pokazuje mapowanie pól: klucz, grupę, typ i etykietę, bez wartości zgłoszeń. Wycofanie: rollbackOrderAnalyticsBridge(). Zmiana mapowania w Script Properties wymaga nowego kodu snippetu, bo mapowanie jest w ten kod wpisane. Import wykrywa rozbieżność i kończy się błędem bez zmiany zakładki. Naprawa: rollbackOrderAnalyticsBridge(), potem prepareOrderAnalyticsBridge(), które aktualizuje kod nieaktywnego snippetu i zapisuje migawkę poprzedniego, a na koniec activateOrderAnalyticsBridge(). Nadpisany może zostać wyłącznie snippet przygotowany przez skrypt, czyli o zapisanym ID i z kodem dokładnie takim, jaki skrypt ostatnio wdrożył (skrót w WP_ORDER_ANALYTICS_CODE_DIGEST). Snippet o tej samej nazwie, kod poprawiony ręcznie w WordPressie i aktywny snippet z innym kodem zostają nietknięte, a odmowa pada przed pytaniem o zgodę. Import uruchamia WordPress → Importuj zlecenia do analityki (ZLECENIA ANALITYKA); codzienny trigger jest poza pierwszą wersją.
SEO LIVE i kolejka WP COMMANDS działały niezależnie, co dawało wyścig: polecenie przygotowane wieczorem, poranny live check widzi jeszcze stary stan i wysyła alert o regresji, a polecenie wykonuje się później tego samego dnia. Alert jest wtedy prawdziwy, ale bezużyteczny, bo system zna już zamierzony stan.
Live check rozpoznaje więc różnicę, którą naprawi przygotowana zmiana, i oznacza wiersz jako PENDING CHANGE z numerem oczekującego polecenia, zamiast zgłaszać regresję. Po upływie progu, domyślnie 48 godzin i konfigurowalnego przez Script Property SEO_LIVE_PENDING_GRACE_HOURS, niewykonane polecenie samo staje się alertem: cisza bez końca byłaby gorsza niż fałszywy alarm.
Wyciszenie jest celowo wąskie, bo tłumienie prawdziwej regresji jest znacznie gorsze niż jeden alert za dużo. Tłumione są wyłącznie różnice pokryte jawnie wymienioną parą akcji i pola: robots i tytuł SEO z UPDATE_RANK_MATH_FIELD oraz status z PUBLISH_PAGE. Polecenie musi mieć confirm=YES i status PENDING; tryb próbny, brak potwierdzenia i polecenie już wykonane nie wyciszają niczego. Adres jest dopasowywany po identyfikatorze strony odczytanym z WordPressa, nie po podobieństwie tekstu, a jedna niewyjaśniona różnica znosi wyciszenie całego wiersza.
Monitoring pozostaje read-only wobec WordPressa. Nic z tego mechanizmu nie wykonuje poleceń, nie omija WP_ALLOW_WRITES ani potwierdzenia; prawo do zapisu zostaje wyłącznie w kontrakcie WP COMMANDS.
Sprawdzenie obecności @type chroni przed zniknięciem całego typu danych strukturalnych, ale przepuszcza gorszą regresję: schema jest, tylko opisuje co innego niż strona. Cena w Offer inna niż widoczna, pytanie w FAQPage, którego nie ma w FAQ, dwa węzły podające sprzeczne wartości tego samego pola.
SEO LIVE parsuje więc JSON-LD prawdziwym JSON.parse, spłaszczając @graph, tablice i węzły zagnieżdżone do jednej listy. Uszkodzony blok jest zgłaszany z numerem, bez wypisywania jego treści, i nie przerywa czytania pozostałych.
Kontrole wartości są opcjonalne i opisane w zakładce SEO SCHEMA, którą zakłada SEO / GSC → Przygotuj reguły schema. Reguła to ścieżka Typ.pole, na przykład Offer.price albo FAQPage.mainEntity.name, oraz źródło oczekiwania. Źródło wartość porównuje schema z tym, co wpiszesz, i zgłasza sprzeczne wartości w kilku węzłach; źródło strona wymaga, żeby każda wartość z JSON-LD była widoczna w treści strony. Wiersz bez adresu opisuje regułę wspólną dla wszystkich stron.
Różnice trafiają do tej samej kolumny co pozostałe i mają rozróżnialne początki: nieprawidłowy JSON-LD, brak wartości, sprzeczne wartości, niezgodna wartość. Bez zakładki i bez reguł SEO LIVE działa dokładnie jak wcześniej.
To kontrola spójności danych, nie walidator Google Rich Results: wynik nie mówi nic o kwalifikacji do rich resultów ani o rankingu.
Komórka arkusza mieści 50 000 znaków, więc pełna wymiana treści długiej strony nie mieściła się w kolumnie value polecenia. Treść przychodzi wtedy z zakładki WP PAYLOADS, podzielona na części, a w WP COMMANDS zostaje sama referencja payload:<identyfikator>.
WordPress → Przygotuj zakładkę payloadów tworzy zakładkę z właściwymi nagłówkami i tłumaczy sposób użycia. Części są sklejane w kolejności kolumny part, która musi iść od 1 bez luk i duplikatów; niekompletny payload zatrzymuje polecenie przed snapshotem i przed jakimkolwiek zapisem, bo strona z dziurą w treści jest gorsza niż polecenie, które się nie wykonało.
Nośnikiem jest zakładka, a nie plik na Dysku. Dysk wymagałby nowego zakresu OAuth i ponownej autoryzacji projektu, a treść strony i tak należy do tego samego arkusza co reszta pracy.
Cały model bezpieczeństwa działa bez zmian: WP_ALLOW_WRITES, WP_DRY_RUN, confirm=YES, snapshot przed zmianą, idempotencja po command_id. Po zapisie treść jest porównywana skrótem SHA-256 zamiast kopiowaniem HTML-a do komórki wyniku, a rozjazd kończy się błędem wskazującym najczęstszą przyczynę, czyli filtrowanie treści przez WordPressa przy braku uprawnienia unfiltered_html. Tryb próbny opisuje duży payload rozmiarem i skrótem, nie treścią.
- Jeden lock skryptu (
Lock.gs,LockService.getScriptLock) obejmuje każdy import GSC/GA4 i całą pętlę Wykonaj polecenia. To krótkietryLock(5 s) bez kolejkowania: drugie uruchomienie, które zastanie lock zajęty, kończy się komunikatemInne uruchomienie jeszcze trwa (…). - Jeden pisarz stanu przebiegów (#204). Rekord zadania (
LAST_IMPORT_*,LAST_RUN_*), wierszIMPORT LOG, incydent i komórkę statusu zapisuje wyłącznie wykonanie, które trzyma lock. Rejestrator przebiegu bierze lock przed odczytem rekordu i trzyma go do końca obsługi wyniku. Przed zwolnieniem wołaSpreadsheetApp.flush(). Strażnik aktualności też działa pod lockiem. 26.09.2026 dwa nakładające się ręczne importy GSC zgubiły przez to wierszBŁĄDi incydent, a mail „ponownie działa” nie przyszedł nigdy. - Odmowa locka nie jest przebiegiem. Z menu kończy się oknem z komunikatem, bez rekordu, wiersza w
IMPORT LOGi maila, bo człowiek widzi okno od razu. Z triggera zostawia w Script Properties wpis oczekującyPENDING_RUN_<zadanie>_<uuid>. Przejmuje go następne wykonanie z lockiem: dopisuje wierszBŁĄDz czasem odmowy, w kolejności czasu, aktualizuje rekord i incydent, a wpis usuwa dopiero po zapisie. Wyjątek: gdy przejmujący zapisuje w tej samej obsłudze udany przebieg tego samego zadania, odmowa zostaje tylko w logu, bez pary maili „BŁĄD” i „ponownie działa”. Tak samo, gdy rekord zadania ma już przebieg nie starszy niż odmowa: stara odmowa nie cofa stanu. Odmowa późniejsza niż przebieg przejmującego czeka na następnego posiadacza locka, żeby zapisy szły w kolejności czasu. Ubicie wykonania pomiędzy zapisem a usunięciem wpisu daje najwyżej zduplikowany wiersz, nigdy utracony ślad. - Statusy poleceń w
WP COMMANDS:PENDINGjest podejmowane;RUNNINGoznacza przebieg przerwany po zajęciu wiersza (limit czasu Apps Script, awaria). Taki wiersz nigdy nie jest wykonywany ponownie automatycznie: sprawdź stronę w WordPressie, potem ustawERRORalboPENDINGz nowymcommand_id.SKIPPEDoznacza polecenie zapisu odrzucone, bo nie macommand_idalbo wynik dla tegocommand_idjuż istnieje wWP RESULTS; żeby wykonać je ponownie, nadaj nowe id. Polecenia odczytu można powtarzać dowolnie. - Bardzo długie strony a snapshoty: komórka arkusza mieści 50 000 znaków, a treść strony z kreatora bywa dłuższa. Taka treść jest zapisywana w snapshocie obcięta i wyraźnie oznaczona, a rodzaj snapshotu to
PAGE_TRUNCATEDzamiastPAGE. Komenda kończy się sukcesem, ale jej komunikat ostrzega, że snapshot nie posłuży do cofnięcia treści.RESTORE_SNAPSHOTna takim snapshocie odmawia przed jakąkolwiek zmianą, zamiast wgrać uciętą treść i zameldować sukces; treść cofa się wtedy ręcznie z historii wersji WordPressa. To samo ostrzeżenie pojawia się, gdy niepełna okaże się kopia stanu sprzed rollbacku. - Menu WordPress → Wykonaj wiersze DRY_RUN naprawdę prosi o potwierdzenie, przestawia wiersze
DRY_RUNnaPENDINGi wykonuje je; odmawia, dopókiWP_DRY_RUNjestTRUE.
WP_DRY_RUN=TRUE zamienia Wykonaj polecenia w próbę generalną: każde polecenie zapisu przechodzi walidacje, odczyty i snapshot dokładnie jak na produkcji, ale żądanie zapisu jest zatrzymywane tuż przed UrlFetchApp.fetch, a wiersz polecenia dostaje status DRY_RUN z metodą, URL-em i payloadem, które zostałyby wysłane. Odczyty nadal się wykonują. Dry run i prawdziwy zapis dzielą jeden builder żądania (buildWpRequest_), więc podgląd nie może różnić się od produkcji. Dry run działa bez WP_ALLOW_WRITES; bez WP_DRY_RUN blokada zapisów pozostaje bez zmian.
Nic specyficznego dla witryny (domena, nazwa firmy, namespace REST) nie jest zaszyte w źródłach; wszystko żyje w Script Properties, żeby repozytorium mogło pozostać publiczne.
Każdy import GSC i GA4, ręczny albo z codziennego triggera, zapisuje swój wynik w Script Properties (LAST_IMPORT_GSC, LAST_IMPORT_GA4: ostatnie uruchomienie i ostatnie udane uruchomienie z czasem, liczbą wierszy, błędem, czasem trwania). Pokazują to dwa miejsca:
-
Komórki
Konfiguracja GSC!B8iKonfiguracja GA4!B9, po jednej linii, czytelne dla człowieka i dla wszystkiego, co czyta arkusz przez API:Tekst komórki Znaczenie AKTYWNE – ostatni import: 2026-09-05 06:02 | 1234 wierszy | trigger: TAKostatnie uruchomienie się udało, dane są świeże, codzienny trigger zainstalowany BŁĄD 2026-09-06 06:01: <komunikat> | ostatni poprawny import: 2026-09-05 06:02 | trigger: TAKostatnie uruchomienie padło; dane pochodzą z poprzedniego udanego NIEAKTUALNE – …ostatni udany import jest starszy niż 36 godzin (albo go nie ma); nie ufaj danym BRAK IMPORTU – uruchom import z menu | trigger: NIEnigdy nie importowano -
Menu Dane → Status danych: to samo dla obu źródeł plus harmonogram, wynik ostatniego uruchomienia, tryb ręczny/trigger i czas trwania. Odśwież status w komórkach przepisuje komórki (na przykład po zainstalowaniu triggera).
Nieudany przebieg triggera nigdy nie udaje więc świeżego importu, a komórki mówią, czy trigger jest nadal zainstalowany.
Historia i anomalie (arkusz IMPORT LOG, tworzony automatycznie): każde uruchomienie dopisuje wiersz z czasem, źródłem, typem uruchomienia (trigger / ręczny; import dzienny liczy się jako trigger tylko wtedy, gdy wywołał go trigger czasowy Apps Script, ta sama pozycja menu uruchomiona ręcznie to ręczny), liczbą dni w importowanym zakresie (0 przy nieudanych przebiegach, gdzie zakres jest nieznany), wynikiem, liczbą wierszy, czasem trwania, szczegółami, błędem lub ostrzeżeniem oraz — w ostatniej kolumnie — zakresem danych, który import faktycznie pobrał (RRRR-MM-DD..RRRR-MM-DD, #180). Istniejąca zakładka dostaje tę kolumnę sama: etykieta Zakres danych jest dopisywana tylko do pustej komórki nad pustą kolumną, a gdy kolumna jest zajęta czymś innym, wiersze idą bez zakresu, nigdy z błędem. Wiersze starsze niż 90 dni są usuwane niezależnie od tego, gdzie leżą, więc ręczne sortowanie arkusza jest bezpieczne; reguła anomalii również pomija wygasłe wiersze i porządkuje historię po czasie, nie po pozycji wiersza. Po każdym udanym przebiegu liczba wierszy jest porównywana z medianą ostatnich 7 próbek tego samego profilu (źródło + typ uruchomienia + dni), więc codzienny import triggera na 1 dzień nigdy nie jest porównywany z ręcznym uzupełnieniem 90 dni. Próbka to zakres danych, nie przebieg: kilka importów tego samego zakresu liczy się raz (zostaje najnowszy), a import, który powtarza zakres, nie porównuje się z jego wcześniejszym importem — 09.09.2026 ten sam dzień zaimportowany dwa razy zawyżył medianę i dał dwa fałszywe alarmy. Wiersze sprzed tej zmiany, bez zakresu, liczą się każdy osobno. Mniej niż 7 próbek oznacza brak alarmu o spadku, ale zero wierszy alarmuje zawsze, gdy profil wcześniej zwracał dane (mało danych: 0 wierszy, a wcześniej ten profil zwracał dane (ostatnio <n>)) — dawniej przy krótkiej historii przechodziło bez śladu. Od #281 zero alarmuje też wtedy, gdy dane zwracało źródło w profilu o innej liczbie dni (mało danych: 0 wierszy, a wcześniej to źródło zwracało dane (ostatnio <n>)): przebieg uzupełniający lukę (2 dni i więcej) ma własny profil bez próbek, więc 4.10.2026 zero wierszy po otwartym incydencie z 3.10 przeszło bez alarmu, a incydent zamknął się mailem „Dane wróciły do normy” z „Wiersze: 0”. Baza dla tego zera to udane przebiegi źródła tego samego typu uruchomienia (trigger albo ręczny) z okna retencji, z dowolną liczbą dni, bez zakresu bieżącego przebiegu. Incydent zamyka dopiero przebieg bez anomalii, nie sam wynik powyżej zera: niski niezerowy wynik poniżej połowy mediany swojego profilu go podtrzymuje. Progi, mediany i bazy klasowe GA4 bez zmian. Po rozgrzewce zero albo mniej niż połowa mediany dopisuje UWAGA: mało danych: <n> wierszy vs mediana <m> do komórki statusu, okna Status danych i wiersza logu. Sam import nadal liczy się jako udany; ostrzeżenie to sygnał, żeby zajrzeć do źródła.
GA4: osobne bazy dla dni roboczych i weekendu (#180). Ruch ma tygodniowy rytm — w pomiarze z 05–17.09.2026 cztery dni weekendowe miały 8–13 wierszy, dni robocze 15–38 — więc mediana kolejnych dni jest zawsze wartością z dnia roboczego, a zwykła sobota leżała tuż przy progu. Dla importów GA4 z profili jednodniowych próbka dostaje klasę z daty danych (import z poniedziałku pobiera sobotę, więc to sobota): sobota i niedziela to weekend, reszta to dni robocze. Bieżący import jest porównywany wyłącznie ze swoją klasą: dni robocze z medianą 5 ostatnich dni roboczych (rozgrzewka 5, około tygodnia), weekend z medianą 4 ostatnich dni weekendowych (rozgrzewka 4, około dwóch tygodni); treść alarmu podaje klasę, np. vs mediana 27 (dni robocze). Wiersze sprzed wprowadzenia zakresu danych nie mają klasy i do baz klasowych nie wchodzą. Próg połowy mediany i alarm zera — bez zmian; zero liczy się względem całego profilu, więc pierwsza sobota z zerem po dniach roboczych z danymi też alarmuje. Zanim sezonowość weszła, sprawdzono, że niski weekend jest prawdziwy, a nie efektem niekompletnych danych: ponowny import 90 dni dał dla 12 i 13.09 co do wiersza te same liczby co import dzienny z opóźnieniem 2 dni. GSC takiego wzoru nie pokazało i zostaje przy jednej bazie.
Co znaczy „mało danych” i czego nie dowodzi. Alert mówi tylko, że import zwrócił wyraźnie mniej wierszy niż zwykle w porównywalnych warunkach — mniej niż połowę mediany swojej bazy albo zero, gdy wcześniej były dane. Nie mówi, dlaczego: spadek ruchu, zmiana w tagowaniu, opóźnienie przetwarzania po stronie Google i problem z importem wyglądają w tej liczbie tak samo. Liczba wierszy to liczba kombinacji wymiarów (strona × kanał × źródło × …), a nie liczba sesji ani użytkowników: dzień z tym samym ruchem skupionym na mniejszej liczbie stron da mniej wierszy, a dane GA4 potrafią jeszcze po kilku dniach zmienić liczbę kombinacji (08.09.2026: 22 wiersze raportu landing przy imporcie, 16 przy ponownym imporcie). Alert jest więc zaproszeniem do sprawdzenia źródła, nie diagnozą.
Źródło zewnętrzne, na przykład arkusz, do którego integracja dopisuje zgłoszenia z formularza, może być dostępne, a mimo to przestać dostawać nowe rekordy. Świeżość takiego źródła liczy natywna formuła Arkuszy z NOW(), nie wyzwalacz i nie funkcja niestandardowa. Arkusz przelicza ją sam, więc przechodzi z ACTIVE do STALE także wtedy, gdy nie działa żaden wyzwalacz Apps Script (19–26.09.2026 stały wszystkie naraz, #198). Funkcja niestandardowa nie zadziałałaby tu z dwóch powodów: jej argumenty muszą być deterministyczne, więc nie przyjmie NOW(), a bez zmiany komórek wejściowych w ogóle się nie przelicza.
Formuła potrzebuje dwóch komórek i nie czyta niczego więcej, ani treści zgłoszeń, ani danych osobowych:
- znacznik ostatniego rekordu (
lastTimestamp, niżejB2): wartość daty i czasu Arkuszy albo tekst dokładnieRRRR-MM-DD GG:MM:SS, czytany strukturalnie jako czas w strefie arkusza, bez parsera zależnego od ustawień regionalnych. Każdy inny tekst, pusta komórka, nieistniejąca data (np.2026-02-30, godzina24) albo rok przed 1900 toERROR; - próg w godzinach (
maxAgeHours, niżejC2): liczba większa od zera, na przykład1,5. Próg należy do instalacji i jest świadomą tolerancją na fałszywe alarmy.
| wynik | znaczenie |
|---|---|
ACTIVE |
znacznik jest poprawny, a jego wiek nie przekracza progu (granica włącznie) |
STALE |
znacznik jest poprawny, ale starszy niż próg |
ERROR |
brak albo zły znacznik, zły próg albo znacznik z przyszłości (niespójność zegara lub danych, nie świeże źródło) |
Wiek liczy się w pełnych sekundach czasu ściennego strefy arkusza, tak jak Arkusze odejmują numery seryjne dat. W noc zmiany czasu różnica jest więc o godzinę większa albo mniejsza od rzeczywistej.
Formuła do wklejenia. Separator argumentów zależy od ustawień regionalnych pliku (Plik → Ustawienia → Język). Formuła z niewłaściwym separatorem daje błąd, więc nie ma jednej wersji dla wszystkich plików. Dla pliku z przecinkiem dziesiętnym (np. polskie ustawienia), znacznik w B2, próg w C2:
=IFERROR(LET(stamp;B2;limit;C2;current;NOW();serial;IF(ISTEXT(stamp);IF(REGEXMATCH(stamp;"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$");LET(yr;VALUE(MID(stamp;1;4));mon;VALUE(MID(stamp;6;2));dy;VALUE(MID(stamp;9;2));hr;VALUE(MID(stamp;12;2));mnt;VALUE(MID(stamp;15;2));sek;VALUE(MID(stamp;18;2));IF(AND(yr>=1900;mon>=1;mon<=12;dy>=1;dy<=DAY(EOMONTH(DATE(yr;mon;1);0));hr<=23;mnt<=59;sek<=59);DATE(yr;mon;dy)+TIME(hr;mnt;sek);NA()));NA());IF(ISDATE(stamp);stamp;NA()));age;ROUND((current-serial)*86400);IF(OR(NOT(ISNUMBER(limit));ISDATE(limit);limit<=0);"ERROR";IF(age<0;"ERROR";IF(age<=limit*3600;"ACTIVE";"STALE"))));"ERROR")
Dla pliku z kropką dziesiętną (np. ustawienia amerykańskie):
=IFERROR(LET(stamp,B2,limit,C2,current,NOW(),serial,IF(ISTEXT(stamp),IF(REGEXMATCH(stamp,"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$"),LET(yr,VALUE(MID(stamp,1,4)),mon,VALUE(MID(stamp,6,2)),dy,VALUE(MID(stamp,9,2)),hr,VALUE(MID(stamp,12,2)),mnt,VALUE(MID(stamp,15,2)),sek,VALUE(MID(stamp,18,2)),IF(AND(yr>=1900,mon>=1,mon<=12,dy>=1,dy<=DAY(EOMONTH(DATE(yr,mon,1),0)),hr<=23,mnt<=59,sek<=59),DATE(yr,mon,dy)+TIME(hr,mnt,sek),NA())),NA()),IF(ISDATE(stamp),stamp,NA())),age,ROUND((current-serial)*86400),IF(OR(NOT(ISNUMBER(limit)),ISDATE(limit),limit<=0),"ERROR",IF(age<0,"ERROR",IF(age<=limit*3600,"ACTIVE","STALE")))),"ERROR")
Inne adresy komórek daje generator sourceFreshnessFormula_(znacznik, próg, { separator }) w src/SourceFreshness.gs. Test sprawdza, że obie formuły wyżej są jego wynikiem. Ta sama semantyka w JS, sourceFreshness_(), służy do testów. W trybie testowym generator przyjmuje zamiast NOW() adres komórki ze stałą chwilą ({ now: 'E1' }), żeby na kopii arkusza sprawdzić granicę progu deterministycznie.
Przeliczanie. NOW() przelicza się przy każdej zmianie w pliku i dodatkowo według ustawienia Plik → Ustawienia → Obliczenia → Przeliczanie. Bez okresowego przeliczania („przy zmianie i co minutę” albo „co godzinę”) nieotwarty i niezmieniany plik nie przejdzie do STALE. Ustawienie decyduje więc o czułości sygnału i trzeba je zapisać w instalacji razem z progiem.
Formuła używa angielskich nazw funkcji. Test przeszedł w pliku z polskim językiem wyświetlania przy zaznaczonym Plik → Ustawienia → Zawsze używaj angielskich nazw funkcji. Zachowania bez tej opcji nie sprawdzaliśmy.
Odczyt bez otwierania pliku (zmierzone 2026-09-29, #197). Endpoint gviz (/gviz/tq?tqx=out:csv) czytał zamknięty plik z przeliczaniem co minutę i oddał STALE z NOW() z chwili odczytu, a nie z chwili zamknięcia pliku. Drugi odczyt po 22 s dał tę samą chwilę, więc wynik jest trzymany około minuty. Czytelnik maszynowy dostaje więc przez gviz sygnał najwyżej o minutę starszy. Sheets API v4 (values.get) nie było mierzone.
Czego STALE nie mówi. Świeżość to nie zdrowie. STALE znaczy tylko, że od progu nie pojawił się nowszy rekord. Nie odróżnia dnia bez zgłoszeń od zerwanej integracji ani awarii formularza. Silniejszy sygnał, czyli porównanie najwyższego identyfikatora rekordu w źródle i w arkuszu, jest poza zakresem.
Prezentacja. Dostępność źródła (czy mechanizm odpowiada), jeśli jest mierzona, i świeżość trzymamy w osobnych komórkach. Status łączny, jeśli instalacja go składa, nie może pokazać ACTIVE przy świeżości STALE. Etykiety wyników można przetłumaczyć w warstwie prezentacji. Produkt nie ma dashboardu źródeł zewnętrznych, a jego instalacja należy do właściciela arkusza. Alert e-mail o STALE nie jest częścią tego mechanizmu: niezależny od Apps Script alert, który działa przy martwych wyzwalaczach i bez otwierania arkusza, opisuje docs/freshness-monitor.md (#295).
Luka uzupełnia się sama. Import dzienny pobiera dzień dziś − dailyLagDays oraz dni brakujące od ostatniego dnia z danymi, czyli największej daty w kolumnie A zakładki GSC RAW, najwyżej 7. Przy dłuższej luce pobiera 7 najnowszych dni, a ostrzeżenie podaje, które dni uzupełnić ręcznie (SEO / GSC → Importuj ostatni zakres). Przy zakładce bez dat pobiera jeden dzień, jak dawniej. Początek zakresu nie zależy od wyniku poprzedniego przebiegu (#215): gdy Google publikuje dzień z opóźnieniem i API zwraca dla niego zero wierszy, przebieg dostaje ostrzeżenie brak danych za … (API nie zwróciło wierszy), a następny import dzienny pobiera ten dzień ponownie. Dotyczy to zakładki, która ma datę wcześniejszą niż cel przebiegu i żadnej późniejszej. Na pustej zakładce zero wierszy nie zostawia żadnej daty, a data późniejsza niż cel przesuwa początek następnego zakresu za ten dzień. W obu przypadkach następny przebieg zaczyna od nowego celu, więc ostrzeżenie mówi, że dnia nie pobierze ponownie, i radzi ręczny import zakresu (#225). Wiersz IMPORT LOG podaje rzeczywistą liczbę dni i zakres, a przebieg kilkudniowy ma własną bazę porównawczą anomalii i nie zaniża mediany jednego dnia.
Zapis samych importowanych dni. Dawniej każdy przebieg czytał, czyścił i zapisywał całą zakładkę GSC RAW, więc czas rósł z jej rozmiarem. Import dzienny może zamiast tego usunąć wiersze importowanych dni i dopisać nowe za ostatnią niepustą komórką kolumny A. Kolejność pozostałych wierszy się nie zmienia, a kod nigdy nie zapisuje kolumn K–L (Pozycja×wyświetlenia, Data_num). Te kolumny liczy formuła spoza kodu i zostają poprawne po usunięciu i dopisaniu wierszy tylko wtedy, gdy liczy je jedna formuła rozlana na całą kolumnę. Z samego tekstu formuły nie da się tego dowieść, bo =ARRAYFORMULA(SUM(A2:A)) zwraca jedną wartość. Dlatego nowa ścieżka rusza tylko wtedy, gdy w każdej z kolumn K i L:
- jest dokładnie jedna formuła, w wierszu 1 albo 2;
- jej tekst jest znak w znak taki jak wzorzec w
GSC_KL_ANCHOR_FORMULAS; - jej wartość nie jest błędem (
#REF!,#N/A…).
Kotwica w wierszu 2 stoi zwykle obok danych A2:J2, a usunięcie wiersza 2 zabrałoby ją razem z nimi. Dlatego gdy data w A2 należy do importowanego zakresu, import idzie ścieżką dotychczasową. Wiersz 1 nie jest usuwany nigdy.
Każdy inny stan, w tym brak właściwości albo zły JSON, to zapis całej zakładki, jak dawniej, z ostrzeżeniem K–L: zapis całej zakładki, bo …. Ostrzeżenie podaje kolumnę, niespełniony warunek i początek formuły. Ręczny import zakresu zawsze zapisuje całą zakładkę.
Zatwierdzenie wzorca. Pierwszy import po wdrożeniu idzie ścieżką dotychczasową i zapisuje w logu wykonania linię [import GSC] kotwice K–L (pełny tekst): {"K":"…","L":"…"}. Właściciel arkusza sprawdza, że obie formuły liczą wartość dla każdego wiersza (np. ARRAYFORMULA(IF(A2:A="",,…))), i wpisuje ten JSON do GSC_KL_ANCHOR_FORMULAS. Od następnego przebiegu działa nowa ścieżka. Gdy formuły w arkuszu się zmienią, a właściwość nie, import wraca do zapisu całej zakładki z ostrzeżeniem.
Czas etapów. Importy GSC i GA4 zapisują w logu wykonania czas każdego etapu, np. [import GSC] zapytania API (452 wierszy): 12345 ms (od startu 12345 ms), potem rozpoznanie K–L, odczyt, usunięcie albo czyszczenie, zapis, formaty i obsługę wyniku. Wpis powstaje po zakończeniu etapu, więc rejestr wykonań Apps Script pokazuje go także dla przebiegu ubitego limitem, do ostatniego etapu, który się skończył.
Import GSC mierzy osobno odczyt kolumny A i pętlę po jej wierszach, zarówno przy wyznaczaniu zakresu („odczyt kolumny A do zakresu”, „ostatni dzień z danymi … w tym N dat”), jak i przy zapisie („rozpoznanie importowanych dni”, „usunięcie wierszy importowanych dni”). 13.10.2026 przebieg ubito przed końcem pierwszego etapu i z logu nie dało się ustalić, który krok trwał (#220). Funkcja diagnozaDatGsc uruchomiona z edytora Apps Script mierzy to samo poza importem: pierwszy i drugi odczyt kolumny A oraz pętlę z Utilities.formatDate dla każdej daty wobec pętli z pamięcią po wartości daty. Niczego nie zapisuje.
Pętle po kolumnie A (gscLastDataDay_, appendGscDays_, replaceRange_) formatują każdą różną chwilę raz: cachedFormatDate_ (Dates.gs) trzyma pamięć kluczowaną getTime() w domknięciu jednego użycia i niczego nie przenosi między wywołaniami ani przebiegami (#229). Liczba kosztownych wywołań Utilities.formatDate zależy więc od liczby różnych chwil (kilkadziesiąt), a nie od liczby wierszy; iteracja po kolumnie nadal ma koszt proporcjonalny do liczby wierszy. diagnozaDatGsc liczy wariant z pamięcią tym samym pomocnikiem, więc mierzy kod produkcyjny.
Alerty wysyła MailApp (zakres script.send_mail; pierwsze wdrożenie z tym zakresem wymaga jednorazowej ponownej autoryzacji skryptu) na adres z ALERT_EMAIL. Nie wysyłają się przy każdym zdarzeniu, tylko per incydent, jeden na źródło, przechowywany w tym samym rekordzie LAST_IMPORT_*:
| Przejście | Co się dzieje |
|---|---|
| OK → problem | incydent otwarty, jeden e-mail ze źródłem, czasem, trybem ręczny/trigger, treścią błędu lub anomalii i ostatnim poprawnym importem |
| problem → problem | cisza; incydent aktualizuje tylko powód i szczegóły (błąd po anomalii, nowy komunikat błędu) |
| problem → OK | incydent zamknięty; e-mail Import ponownie działa po błędzie albo Dane wróciły do normy po anomalii — import działał przez cały czas, więc „ponownie działa” byłoby nieprawdą (#180) — chyba że ALERT_RECOVERY=FALSE |
Problemem jest nieudany przebieg (BŁĄD, w tym odmowa locka przy uruchomieniu z triggera, zgłaszana przez następne wykonanie z lockiem, i import ubity limitem czasu, zgłaszany przez strażnika), anomalia liczby wierszy (UWAGA, mało danych) albo udany import po ubitym poprzednim (UWAGA, #209). Inne ostrzeżenia importu, np. o luce w danych albo o zapisie całej zakładki, są widoczne w komórce statusu i w IMPORT LOG, ale incydentu nie otwierają. Odmowa locka przy uruchomieniu z menu nie wysyła maila (#204). Tematy zaczynają się od [wordpress-automation]; każda treść kończy się URL-em arkusza i wdrożoną wersją. Wysyłka jest best-effort: awaria MailApp (limit dzienny, zły adres) trafia do logu i nigdy nie zmienia wyniku importu ani strażnika. Incydent, którego e-mail otwierający nie mógł zostać wysłany (brak ALERT_EMAIL, limit), dostaje powiadomienie raz przy kolejnym wystąpieniu, gdy wysyłka stanie się możliwa, a potem milczy jak zwykle.
Nieaktualne dane nie mają przebiegu, na który można zareagować, więc codzienny strażnik (sprawdzAktualnoscImportow, menu Dane → Sprawdź aktualność teraz (alerty)) sprawdza oba źródła: źródło w stanie NIEAKTUALNE albo BRAK IMPORTU otwiera incydent stale, a wszystkie takie źródła trafiają do jednego zbiorczego e-maila; przy otwartym incydencie strażnik milczy. Gdy źródło znowu jest świeże, strażnik zamyka incydent (e-mail o powrocie do normy, ten sam przełącznik). Incydenty otwarte przez nieudany przebieg zostawia ścieżce importu. Pozycja menu pokazuje okno z oboma źródłami, liczbą otwartych i zamkniętych incydentów oraz informacją, czy e-mail wyszedł, a jeśli nie, to dlaczego (brak adresu, nieprawidłowy adres, błąd MailApp). Dane → Włącz codzienne alerty e-mail instaluje trigger strażnika ok. 08:00, po importach GSC i GA4; okno mówi, gdzie trafiają alerty, albo ostrzega, że ALERT_EMAIL brakuje lub jest nieprawidłowe. Status danych pokazuje otwarty incydent per źródło, adresata i to, czy trigger strażnika jest zainstalowany.
Arkusz URL INSPEKCJA, kolumna A = adresy do monitorowania (tworzony z nagłówkiem przy pierwszym uruchomieniu). SEO / GSC → Sprawdź indeksowanie (URL INSPEKCJA) woła API inspekcji URL Search Console dla każdego adresu i zapisuje w tym samym wierszu: werdykt (ZAINDEKSOWANY (PASS), WYKLUCZONY (NEUTRAL), BŁĄD INDEKSOWANIA (FAIL), NIEZNANY), stan pokrycia w brzmieniu Google (na przykład Excluded by 'noindex' tag), kanoniczny wg Google i wg strony, ostatni crawl, stan robots.txt, czas sprawdzenia. Werdykt albo pokrycie inne niż w poprzednim przebiegu jest oznaczane w kolumnie Zmiana jako ZMIANA: stare → nowe; stan bez zmian czyści flagę. Jeden błędny adres trafia do kolumny Błąd z czasem sprawdzenia i zachowuje poprzednie wartości; pozostałe wiersze są przetwarzane dalej. Adresy bez http(s):// są odrzucane bez żądania.
Wynik to stan w indeksie Google, nie stan opublikowanej strony: po zmianie noindex, canonicala albo treści wiersz zmieni się dopiero po ponownym crawlu (sprawdzenie stanu live to osobne narzędzie, poniżej). API pozwala na 2000 inspekcji dziennie na witrynę; jeden przebieg obsługuje najwyżej 150 adresów i zgłasza resztę jako pominiętą. Adresy są przetwarzane najpierw te nigdy niesprawdzone, potem od najdawniej sprawdzonych (kolumna Sprawdzono), więc dłuższa lista rotuje w kolejnych przebiegach, zamiast zawsze zaczynać od góry. Arkusz, który ma już adresy, ale nie ma nagłówka, dostaje nagłówek wstawiony nad nimi. Włącz cotygodniową inspekcję URL instaluje trigger tygodniowy (poniedziałek, ok. 07:00), który wykonuje to samo sprawdzenie bez okna. Przebieg trzyma wspólny lock skryptu i korzysta z istniejącego zakresu Search Console tylko do odczytu.
Arkusz SEO LIVE: URL w kolumnie A, oczekiwania w B..H oraz M–N (tworzony z nagłówkiem przy pierwszym uruchomieniu). SEO / GSC → Sprawdź strony live (SEO LIVE) pobiera każdy adres przez UrlFetchApp (bez logowania, przekierowania śledzone ręcznie do 5 skoków) i porównuje go z oczekiwaniami: końcowy status HTTP (pusto = 200), końcowy URL po przekierowaniach (pusto = sam adres, więc każde przekierowanie jest różnicą), <title>, pierwszy <h1>, <link rel="canonical">, robots (index domyślnie albo noindex; liczą się meta robots/googlebot i nagłówek X-Robots-Tag) oraz wartości @type z JSON-LD wypisane po przecinku. Puste oczekiwania są pomijane, poza statusem i robots. Wiersz dostaje OK, UWAGA: n różnic(e) z każdą różnicą wypisaną jako co jest (oczekiwano czego) albo BŁĄD z komunikatem sieci; jeden błędny adres nigdy nie zatrzymuje pozostałych. Kolumna L powtarza werdykt z indeksu Google z URL INSPEKCJA dla tego samego adresu, więc stan live i stan w indeksie stoją obok siebie i są tak podpisane.
Oczekiwane i zakazane fragmenty HTML (kolumny M i N). Najczęstsza regresja w praktyce to nie zmiana title, tylko powrót ustawienia wtyczki, który zostawia w HTML charakterystyczny ślad. Oczekiwane w HTML wymienia fragmenty, z których każdy musi wystąpić; Zakazane w HTML — fragmenty, z których żaden nie może. Jeden fragment na linię (separator znakowy odpada, bo | występuje normalnie w skryptach inline), dopasowanie dosłowne na surowym HTML odpowiedzi, bez wykonywania JavaScriptu i bez wyrażeń regularnych. Białe znaki są normalizowane do jednej spacji po obu stronach, wielkość liter — nie. Puste komórki znaczą „bez kontroli”. Różnica w tych dwóch kolumnach nigdy nie jest wyciszana oczekującym poleceniem z WP COMMANDS: dla dowolnego fragmentu HTML nie ma deterministycznego odwzorowania na polecenie, a dopasowanie „po podobieństwie” udawałoby wiedzę, której nie ma.
Kolumny są dopisywane na końcu, za Indeks Google, a nie wstawiane po oczekiwaniach: zapis wyników idzie na sztywno od kolumny 9, więc przesunięcie I–L sprawiłoby, że skrypt czytałby własny Wynik jako oczekiwanie i nadpisywał je w tym samym przebiegu. Etykiety M1/N1 dopisuje się idempotentnie i tylko wtedy, gdy kolumna jest wolna — pusta musi być i komórka nagłówka, i używana część kolumny pod nią, wliczając formuły. Cudza zawartość zatrzymuje cały przebieg komunikatem o konflikcie schematu, zamiast zostać po cichu odczytana jako konfiguracja kontroli.
Włącz codzienny live check SEO instaluje trigger dzienny (ok. 09:00). Przebieg z triggera wysyła jeden e-mail (na ALERT_EMAIL, best-effort) wymieniający wyłącznie nowe różnice, czyli wiersze, które w poprzednim przebiegu były OK albo puste; utrzymująca się różnica nie jest powtarzana, pełnym obrazem jest arkusz.
SEO / GSC → Sprawdź sitemapy (SITEMAPY) wypisuje sitemapy skonfigurowanej właściwości przez API Sitemaps w Search Console i przepisuje arkusz SITEMAPY: ścieżka, typ (indeks albo zwykła sitemapa), czas zgłoszenia i ostatniego pobrania, flaga oczekiwania, liczba zgłoszonych adresów, ostrzeżenia, błędy, stan i czas sprawdzenia. Arkusz jest migawką API, nie listą do edycji. Stan to OK albo UWAGA dokładnie w tych przypadkach: errors > 0, sitemapa oczekująca dłużej niż 7 dni od zgłoszenia, sitemapa wymieniona w opcjonalnej Script Property EXPECTED_SITEMAPS (adresy po przecinku), której Search Console nie ma (dostaje własny wiersz), albo błąd API. Czas ostatniego pobrania jest wyłącznie informacyjny; Google nie traktuje starego pobrania jako usterki, więc skrypt też nie. Podsumowanie jest zapisywane w SITEMAPS_STATUS i pokazywane jako jedna linia w Dane → Status danych, wraz z błędem API, jeśli ostatnie sprawdzenie padło.
sitemaps.list w Search Console zwraca stan sitemap, nie ich zawartość, więc SITEMAPY pokazuje liczbę zgłoszonych adresów, a nie ich listę. SEO / GSC → Odśwież adresy z sitemap (SITEMAP URLS) pobiera XML każdej sitemapy witryny, rozwija indeksy do plików potomnych i zapisuje arkusz SITEMAP URLS: adres, sitemapa źródłowa, lastmod, czas odczytu. Adresy są deduplikowane po normalizacji, rozszerzenia obrazkowe (image:loc) nie są brane za adresy stron, a limity 30 plików i 5000 adresów chronią przed sitemapą wskazującą na siebie albo ogromną; przekroczenie limitu jest zgłaszane wprost. Sitemapy spakowane (.xml.gz) są rozpakowywane przed parsowaniem, a odpowiedź 200, która nie jest XML-em sitemapy (na przykład strona błędu), jest zgłaszana jako błąd zamiast po cichu dawać zero adresów. Siatka arkusza jest powiększana przed zapisem, bo nowy arkusz Google ma tylko 1000 wierszy.
Z tej listy brakujące adresy trafiają do SEO LIVE i URL INSPEKCJA, po jednym wierszu, wyłącznie do kolumny A. Dzięki temu nowa strona nie wymaga pamiętania o dwóch dodatkowych zakładkach, a puste oczekiwania w SEO LIVE sprawdzają dokładnie to, czego się chce od adresu z sitemapy: status 200, brak przekierowania i brak noindex.
Synchronizacja tylko dopisuje. Sitemapa jest listą adresów kanonicznych przeznaczonych do indeksowania, a nie listą wszystkich stron: celowe przekierowania, noindex i strony techniczne są poza nią i to często właśnie je trzeba pilnować. Adres monitorowany, którego nie ma w sitemapie, nigdy nie jest usuwany; okno wypisuje go jako „monitorowany mimo braku w sitemapie” i decyzję zostawia człowiekowi. Ręcznie dopisany wyjątek jest więc trwały i nie potrzebuje osobnej listy. Istniejące wiersze zachowują oczekiwania i wyniki, a drugie uruchomienie niczego nie dopisuje.
Włącz cotygodniowe odświeżanie z sitemap instaluje trigger w poniedziałki około 06:00, godzinę przed inspekcją URL, więc nowe adresy trafiają do inspekcji w tym samym przebiegu tygodnia. Podział ról zostaje bez zmian: SEO LIVE mówi, co strona serwuje teraz, a URL INSPEKCJA, co Google ma w indeksie.
Zmieniona strona jest widoczna dla użytkowników od razu, ale w wynikach Google dopiero po ponownym crawlu. SEO / GSC → Kolejka recrawl (RECRAWL QUEUE) zestawia datę zmiany z datą ostatniego crawla i mówi, co z tego wynika. Nic nie jest zgłaszane do Google automatycznie: dla zwykłych stron nie ma publicznego API odpowiadającego przyciskowi Poproś o zindeksowanie, a Indexing API jest przeznaczone dla innych typów treści. To narzędzie tylko wskazuje, którą stronę zgłosić ręcznie.
Nazwę arkusza rejestru zmian ustawia Script Property CHANGE_LOG_SHEET_NAME; bez niej obowiązuje dotychczasowa Dziennik zmian, więc istniejąca instalacja nie wymaga migracji. Bezpieczna kolejność przy zmianie nazwy to najpierw ustawienie właściwości, potem przemianowanie zakładki, na końcu uruchomienie kolejki i sprawdzenie kolumny ze źródłem daty. Brak wskazanego arkusza jest zgłaszany jego nazwą w raporcie, a nie zastępowany pustym źródłem dat: cicha pustka wyglądałaby jak brak zmian, co jest fałszem.
Wszystko liczone jest z danych, które już są w pliku, bez ani jednego zapytania do API: lastmod z SITEMAP URLS, ręczny rejestr zmian (jeśli ma kolumnę z adresem i kolumnę z datą; nowsza data wygrywa z lastmod), ostatni crawl i werdykt z URL INSPEKCJA, stan produkcyjny z SEO LIVE.
| Status | Kiedy |
|---|---|
AKTUALNE |
Google odwiedził stronę po ostatniej zmianie |
OCZEKUJE NA RECRAWL |
zmiana nowsza niż crawl, ale próg oczekiwania jeszcze nie minął |
WARTO POPROSIĆ RĘCZNIE |
minął próg (domyślnie 7 dni, RECRAWL_STALE_DAYS), albo strona działa, a Google nie ma jej w indeksie |
BRAK CRAWLA |
Google nigdy nie odwiedził tego adresu |
BRAK DATY ZMIANY |
ani lastmod, ani wpis w dzienniku, więc nie ma na czym oprzeć rekomendacji |
WYKLUCZONA / NIE DOTYCZY |
adres spoza sitemapy, celowy noindex, przekierowanie albo ręczne wyciszenie |
Rekomendacje dostają wyłącznie adresy z sitemapy, czyli te przeznaczone do indeksowania. Celowe przekierowania i strony z noindex są monitorowane, ale nigdy nie trafiają na listę do zgłoszenia. Wpisanie TAK w kolumnie Wyciszone wyłącza adres na stałe i przetrwa przepisanie arkusza.
Włącz codzienną kolejkę recrawl instaluje trigger około 10:00, po live checku. E-mail wychodzi wyłącznie o nowych rekomendacjach: strona, która czeka od tygodnia, nie wraca codziennie w kolejnej wiadomości. Znacznik powiadomienia czyści się, gdy Google w końcu odwiedzi stronę, więc następny taki przypadek zostanie zgłoszony ponownie. Jedna wiadomość zawiera najwyżej 50 adresów, a oznaczana jako zgłoszona jest dokładnie ta porcja, więc przy dłuższej liście reszta trafia do maila w kolejnych dniach zamiast przekroczyć limit rozmiaru i nie dojść wcale. Przeliczenie, wysyłka i oznaczenie działają w jednej sekcji krytycznej, więc dwa nakładające się uruchomienia nie wyślą tej samej listy dwa razy.
Dane → Diagnostyka systemu (tylko odczyt) uruchamia smokeTest() i pokazuje po jednej linii na krok: wymagane Script Properties (i to, które opcjonalne są ustawione; wartość ALERT_EMAIL nigdy nie jest wypisywana, poprawna czy nie, tylko to, czy jest skonfigurowana i czy parsuje się jako adres), arkusze konfiguracji i oczekiwane zakładki, odczyt Search Console (lista właściwości, czy siteUrl jest wśród nich i z jakim uprawnieniem), odczyt GA4 Data API (metadane właściwości), odczyt WordPressa (/wp/v2/users/me: kogo loguje hasło aplikacji i czy może edytować strony, plus przełączniki zapisu i dry run), zainstalowane triggery, adresat alertów (skonfigurowany / nieprawidłowy / brak, nigdy sam adres) i stan sitemap. Każdy krok wykonuje się nawet wtedy, gdy wcześniejszy padł, błędy zachowują kod HTTP i nic nigdzie nie jest zapisywane: żaden arkusz, żadna Script Property, żadne wywołanie WordPressa inne niż GET, żaden lock. Nie działa z CI (zob. #54: clasp run i odczyt komórki odrzucone jako zbyt kosztowne w konfiguracji); weryfikacja deployu (#44) dowodzi, że żyją właściwe pliki, model statusu (#43, #42) mówi, czy realne procesy działają, a to okno mówi, dlaczego nie działają.
Plik ma ponad dwadzieścia zakładek i zyskuje kolejną z każdą funkcją, więc kolejność utrzymuje skrypt, nie ręka. Dane → Uporządkuj arkusze koloruje zakładki kategoriami (monitoring zielony, sterowanie pomarańczowy, konfiguracja szary, dane surowe prawie czarny, START fioletowy), ustawia zakładki w tej kolejności i przepisuje arkusz START: wiersz na każdą zakładkę z linkiem, kategorią, informacją, kto ją prowadzi (człowiek / skrypt / oba) i jednym zdaniem o tym, co tam należy. Działanie jest idempotentne, więc drugie uruchomienie zgłasza, że nic się nie zmieniło.
Katalogowane są arkusze, które tworzy sam skrypt (SheetCatalog.gs, jeden wpis na arkusz), oraz te arkusze człowieka, z których skrypt czyta: ręczny rejestr zmian ma wpis w kategorii Analiza (arkusze własne), żeby START mówił, że nagłówki jego kolumn są kontraktem kolejki recrawl. Twoje własne arkusze nigdy nie są przekolorowane ani ukryte, także te opisane w katalogu; zachowują kolejność względną i stoją zaraz za START, bo to je czyta się codziennie. Nowa funkcja tworząca arkusz dodaje jeden wpis do katalogu, inaczej arkusz wyląduje wśród niezarządzanych. Nazwy arkuszy GA4 nadpisane w Konfiguracja GA4 (landingSheet, eventsSheet, businessEventsSheet, adsSheet) katalog rozpoznaje po aktualnej konfiguracji, nie po wartościach domyślnych. Arkusz START o cudzej treści nigdy nie jest kasowany: skrypt rozpoznaje własny spis po podpisie w A1, a przy zbiegu nazw odmawia i prosi o zmianę nazwy albo opróżnienie zakładki.
Dane surowe i logi domyślnie zostają widoczne. Dane → Ukryj arkusze techniczne chowa GSC RAW, surowe zakładki GA4 i IMPORT LOG; Pokaż arkusze techniczne przywraca je. Ukrywanie jest celowo osobną pozycją menu, nie efektem ubocznym porządkowania, a importy działają na ukrytych arkuszach bez zmian.
Workflow deployu i drift checku potrzebują dwóch sekretów repozytorium (Settings → Secrets and variables → Actions):
| Sekret | Wartość |
|---|---|
CLASPRC_JSON |
Pełna zawartość ~/.clasprc.json po lokalnym clasp login. |
APPS_SCRIPT_ID |
Identyfikator projektu Apps Script (edytor Apps Script → Ustawienia projektu → Script ID). |
CLASPRC_JSON rotuje się przez ponowne clasp login i aktualizację sekretu.
Bramka zatwierdzania to ustawienie repozytorium, nie coś, co tworzy workflow. Settings → Environments → production musi mieć włączone Required reviewers i gałęzie wdrożeniowe ograniczone do main i tagów v*. Bez tego workflow deployu wypchnąłby zmiany od razu po uruchomieniu.
Konto Google stojące za CLASPRC_JSON musi też mieć włączone Apps Script API na https://script.google.com/home/usersettings, inaczej clasp push kończy się błędem „User has not enabled the Apps Script API”.
npm ci
npm run lint
npm testW test/ leżą testy jednostkowe Node (node --test, bez dodatkowych pakietów). test/helpers/gas.js ładuje pliki .gs do kontekstu VM z drobnymi zamiennikami usług Google (SpreadsheetApp, PropertiesService, UrlFetchApp, Utilities, ScriptApp, MailApp, LockService), więc wspólny zasięg globalny Apps Script jest odwzorowany, a czyste helpery i warstwa konfiguracji dają się przetestować bez Google:
- parsowanie i przesuwanie dat, dopasowanie hosta/domeny, wyciąganie wierszy GA4, helpery odpowiedzi WordPressa;
- walidacja
getWpConfig_/wpBridgePath_(brakujące albo zniekształcone Script Properties), kształt żądania i parsowanie odpowiedzi wwpFetch_; - domyślne wartości
getGa4Config_, obecność/brakVersion.gs; testGA4end to end na zastubowanych odpowiedziach Admin/Data API (automatyczny wybór właściwości po domenie strumienia, przypadki niejednoznaczne i puste, co trafia do arkusza konfiguracji);- przepływy mostu WordPressa:
testRankMathBridge,getPageRawById_,writeRankMathField_,getPageLayout_,copyPageLayout_, wraz z wierszami wyników dopisywanymi do WP RESULTS i każdą nazwaną ścieżką błędu.
Stub arkusza to prawdziwa siatka komórek: fixture'y zaczynają się od wiersza 1, gas.$cell('Konfiguracja GA4', 'B9') czyta komórkę, gas.$sheet(nazwa) całą siatkę, gas.$alerts okna UI, a fetchRouter([[fragmentUrl, odpowiedź], ...]) rozdziela zastubowane wywołania HTTP.
Wszystko, co naprawdę rozmawia z Sheets, GA4 albo WordPressem, pozostaje pokryte pozycjami menu Sprawdź połączenie / Test … w arkuszu oraz drift checkiem. Trzy pułapki VM przy pisaniu testów: twórz obiekty Date przez gas.$Date, porównuj obiekty zwrócone ze źródeł przez plain() (inny realm, inne prototypy), a Utilities.formatDate w stubie formatuje w strefie maszyny, więc uruchom też TZ=UTC npm test, zanim wypchniesz zmiany.
- Standard: docs/quality/testing-standard.md (warstwy, dziesięć zasad, złoty standard, wzorce zabronione). Planuj testy przez docs/quality/test-matrix-template.md, a dowody zapisuj w szablonie PR-a.
- Bramka pokrycia:
npm run quality:gate -- --changed=base:origin/mainuruchamia testy z pokryciem V8 i egzekwuje dwie zasady: progi per plik z.quality/coverage-policy.json(zapadka, progi idą tylko w górę) i 100 % pokrycia zmienionych linii*.gs. Uzasadnione wyjątki żyją w.quality/changed-lines-ignore.json. - Hook pre-commit:
npm ciustawia gitowi katalog.githooks/(core.hooksPath). Przy każdym commicie hook blokuje poświadczenia i artefakty budowania, lintuje pliki ze stage'a i uruchamia testy oraz bramkę pokrycia na zmienionych liniach*.gs.git commit --no-verifypomija go lokalnie; CI uruchamia tę samą bramkę względemmaini blokuje merge. - CI: job
validateuruchamia lint, testy i bramkę względem commitu bazowego PR-a. - Deploy: workflow deployu uruchamia lint, testy i progi per plik na wdrażanym tagu, po zatwierdzeniu
productioni przedclasp push. Testy pilnują więc każdego etapu: commitu, merge'a, wdrożenia.
Żeby pracować z żywym projektem Apps Script, zaloguj się raz (clasp instaluje npm ci):
npx clasp loginPotem utwórz ignorowany przez gita .clasp.json z identyfikatorem projektu:
{ "scriptId": "<script id>", "rootDir": ".", "scriptExtensions": ["gs"] }scriptExtensions ma znaczenie: clasp 3 domyślnie używa .js, co pobrałoby źródła jako Kod.js obok Kod.gs.
clasp status pokazuje, co zostałoby wypchnięte. Nie uruchamiaj clasp push lokalnie; użyj workflow deployu, żeby każde wdrożenie było zrecenzowane i zapisane.
Issue objęta bramką i będąca w zakresie — P0, P1 albo P2, lub T2 albo T3 — ma jawny stan audytu specyfikacji. Powód: review-ack z Copilotem i Codexem patrzy na kod, a nie na to, czy zadanie w ogóle było dobrze postawione, i błąd w specyfikacji ujawnia się dopiero na PR-ze.
| etykieta | znaczenie |
|---|---|
audit:pending |
specyfikacja czeka na audyt; praca się nie zaczyna |
audit:ok |
specyfikacja zaakceptowana w obecnej wersji treści |
audit:changes |
recenzent zgłosił zastrzeżenia; issue wraca do autora |
Nie zaczynaj pracy nad issue oznaczoną audit:pending albo audit:changes. Brak etykiety audit:* oznacza, że issue jest poza bramką — praca może się zacząć.
Kto napisał specyfikację, ten jej nie audytuje. Ponieważ wszystko idzie z jednego konta GitHuba, autora nie da się odczytać z pola author — rozstrzyga etykieta by:agent, którą agent lokalny nadaje wyłącznie własnym issue. Issue z by:agent audytuje recenzent zewnętrzny; issue bez niej audytuje agent lokalny. Jedna etykieta zamiast pary, bo wtedy brak jest wartością domyślną, a pomyłka jest samonaprawiająca się: nieoznaczona własna issue trafia z powrotem do autora, który rozpozna własny tekst.
Podpisujemy każdą treść issue i każdy komentarz — ostatnią linijką: _— Claude Code (agent lokalny)_ albo _— ChatGPT_. Bez tego nie da się później odróżnić własnego, niezweryfikowanego twierdzenia od audytu drugiej strony, bo wszystko idzie z jednego konta. Konwencja obowiązuje od 2026-09-09T00:00:00Z; brak podpisu po tej chwili znaczy „napisał właściciel”. Wpisy z 2026-09-08 w otwartych issue podpisano wstecz, bo dało się ustalić ich autora. Wpisów sprzed 2026-09-08 nie podpisano i ich autorstwo pozostaje nieustalone — nie wolno go domyślnie przypisać. Podpis mówi, kto pisze, nie jaką rolę akurat pełni — role zmieniają się zależnie od repozytorium. Podpis i prefiks /audit-ok albo /audit-changes rozpoznają werdykt przy czytaniu historii, a bramka liczy go według zasad z następnego akapitu.
Recenzent rozstrzyga komentarzem /audit-ok albo /audit-changes (#231). Bramka liczy komentarz jako werdykt dopiero, gdy spełnia wszystkie warunki naraz:
- Komenda stoi w pierwszej niepustej linii komentarza i nie jest wcięta (cztery spacje albo tabulator to blok kodu, czyli cytowany przykład). Po nazwie nie może stać litera, cyfra ani łącznik:
/audit-ok-nienie jest komendą. - Autor komentarza to osoba uprawniona (właściciel, członek, współpracownik), a komentarz nie był edytowany po publikacji (znacznik
lastEditedAtz API). Komentarz edytowany albo bez danych o edycji nie jest werdyktem; usunięcie komentarza też zmienia stan. - Komentarz jest nowszy niż ostatnia zmiana treści issue. Edycja treści unieważnia rozstrzygnięcie: komenda starsza niż ostatnia zmiana treści przestaje obowiązywać i stan wraca do
audit:pending. - Komentarz pochodzi od strony przeciwnej autorowi treści. Stronę komentarza wyznacza jego podpis zgodny z aplikacją, przez którą powstał (
performed_via_github_app):_— ChatGPT_liczy się tylko z konektora ChatGPT,_— Claude Code (agent lokalny)_tylko bez aplikacji (wysłane przezgh). Komentarz bez podpisu albo z podpisem niezgodnym z aplikacją nie ma strony i nie jest werdyktem.
Autora treści wyznacza zgodność trzech sygnałów: podpis ostatniej linii treści, etykieta by:agent i aplikacja, przez którą utworzono issue. Podpis Claude Code (może mieć w nawiasie dopisek roli po przecinku, np. agent lokalny, koordynator) wymaga by:agent i braku aplikacji; podpis ChatGPT wymaga braku by:agent i konektora ChatGPT. Każda niezgodność, a także brak podpisu treści, daje autorstwo nieustalone: issue zostaje w audit:pending, a bramka nie zgaduje, kto ma rozstrzygać. Brak podpisu nie znaczy więc w bramce „napisał właściciel” (to wskazówka dla ludzi z akapitu wyżej).
Workflow przelicza stan także po edycji i usunięciu komentarza (issue_comment: edited, deleted). Zmieniając treść w trakcie audytu, napisz w komentarzu, co zmieniłeś — etykieta powie, że stan się cofnął, ale nie powie dlaczego.
Triage jest warunkiem wejścia do bramki (#211). Issue bez etykiet P* i T* jest poza zakresem, więc audyt jej nie widzi. Dlatego ten sam przebieg pilnuje triage'u każdej otwartej issue utworzonej od 2026-09-27:
- wymagane rodziny to tutaj
P(dokładnie jedna zP0–P4) iT(dokładnie jedna zT1–T3); listę ustawia--triage-requiredalboAUDIT_TRIAGE_REQUIRED, a dostępna jest też rodzinaarea(co najmniej jednaarea:*); - brakującą wymaganą rodzinę bramka bierze z tabeli w sekcji
## Triagetreści: wiersz zaczynający się odpriorytetdajeP*, odryzykodajeT*, odobszardajearea:*. Wartość stoi w drugiej komórce wiersza i musi zawierać dokładnie jeden token rodziny; przy zerze albo kilku bramka nie zgaduje. Czytana jest pierwsza sekcja## Triage, do następnego nagłówka albo linii poziomej. Bramka czyta HTML, który z treści renderuje GitHub (bodyHTML), więc liczy się wyłącznie to, co GitHub pokazuje jako tabelę: przykład w bloku kodu, komentarz HTML albo linie z|bez wiersza separatora tabelą nie są. Nagłówek i tabela muszą stać na poziomie dokumentu; w cytacie, na liście albo w<details>są traktowane jak przykład. Wartość przekreślona nie jest czytana; w razie wątpliwości issue dostajeneeds-triage; - istniejących etykiet bramka nie nadpisuje ani nie usuwa, a z tabeli nakłada tylko etykiety, które istnieją w repozytorium;
- issue, której nadal brakuje wymaganej rodziny, dostaje
needs-triage; komplet zdejmuje tę etykietę; - stan audytu jest liczony w tym samym przebiegu, już z etykietami z tabeli.
Datę startu triage'u ustawia --triage-active-since albo AUDIT_TRIAGE_ACTIVE_SINCE, osobno od daty startu bramki. Niepoprawna wartość którejkolwiek z tych opcji kończy przebieg błędem, bez zapisu.
Bramka nie objęła wstecz issue sprzed swojego wdrożenia i nie jest mechanicznym zamkiem: GitHub nie potrafi zablokować pracy nad issue, więc egzekwuje ją dyscyplina, a nie mechanizm. Logika żyje w scripts/quality/issue-audit-gate.js (workflow Issue audit gate), pomocniczo w issue-audit-sides.js (strony: autor treści i komentarza) oraz issue-audit-fetch.js (odczyt stanu przez gh); testy w test/issue-audit-gate.test.js. Workflow pobiera wszystkie trzy pliki, a test pilnuje, że żaden lokalny require bramki nie wypadł z listy pobieranych plików.
main jest chroniony: zmiany wchodzą wyłącznie przez pull requesty, CI musi przejść, force-push jest zablokowany. Ochrona jest ścisła, więc gałąź musi być aktualna względem main; PR w konflikcie nie dostaje w ogóle checków pull_request, dopóki nie zmergujesz main do gałęzi.
Tytuły PR-ów muszą trzymać się Conventional Commits (pilnuje tego check PR title). Release Drafter używa prefiksu do ustalenia kolejnej wersji:
feat:/new:— nowa funkcjonalność; wydanie minor.fix:/bug:/hotfix:— poprawka błędu; wydanie patch.docs:— dokumentacja; wydanie patch.chore:/refactor:/ci:/test:/style:— utrzymanie; wydanie patch.
- validate — manifest jest poprawnym JSON-em, brak zdublowanych plików
.gs.gs, ESLint przechodzi na wszystkich źródłach.gs. - secret-scan — Gitleaks skanuje pełną historię pod kątem zacommitowanych sekretów.
- pr-title — tytuł zgodny z powyższym formatem Conventional Commits.
- review-ack — zielony tylko wtedy, gdy (1) recenzja Copilota nie trwa i (2) komentarze botów zostały potwierdzone komentarzem
/reviewed. - pr-template (okres obserwacji, jeszcze niewymagany) — treść PR-a trzyma się szablonu: co najmniej jeden kompletny wiersz matrycy testów, każda pozycja macierzy dowodów odhaczona, oznaczona
N/A (powód)albo jawnie odłożona (po wdrożeniu/after deploy/follow-up/ numer issue), niepuste uzasadnienie deficytu pokrycia oraz linkFixes:alboRefs:bez placeholdera<nr>. Akceptowane są nagłówki polskie i angielskie. Drafty są pomijane; PR-y Dependabota zwolnione. Logika wscripts/quality/pr-template.js, testy wtest/pr-template.test.js; lokalnie uruchomPR_BODY="$(cat body.md)" node scripts/quality/pr-template.jsalbo--body-file body.md.
- Poczekaj, aż Copilot skończy. W trakcie figuruje jako oczekujący recenzent, a check pozostaje czerwony. Bot, który padnie albo wyczerpie limit użycia (Codex robi to regularnie), niczego nie blokuje. Codex potrafi dotrzeć kilka minut po Copilocie: przed merge'em sprawdź wątki jeszcze raz, bo ochrona gałęzi wymaga ich rozwiązania.
- Przeczytaj komentarze. Popraw to, co warto, na resztę odpowiedz, rozwiąż wątki (wymagane przed merge'em).
- Opublikuj komentarz do PR-a zaczynający się od
/reviewed, a po nim krótką notatkę, co zostało przyjęte, a co odrzucone. Musi być nowszy niż ostatni commit i ostatnia recenzja bota (obiekt review albo komentarz w kodzie), więc nowy push albo nowa recenzja bota oznacza nowe/reviewed. Zwykłe komentarze botów do PR-a, na przykład komunikat Codexa o limicie użycia, nie unieważniają potwierdzenia.
Gdy oba boty nie zrecenzowały PR-a z powodu limitów, PR może zostać zmergowany bez ich recenzji (decyzja właściciela z 2026-09-06), pod warunkiem że komentarz /reviewed mówi o tym wprost, a pozostałe checki są zielone.
Check uruchamia się przy każdym pushu i prośbie o recenzję. Każdy komentarz do PR-a (w tym /reviewed) ponawia najnowszą ocenę tego PR-a, więc to komentarz zmienia check na zielony; zakończenie recenzji przez Copilota samo w sobie nie generuje zdarzenia. Jeśli wynik wygląda na nieaktualny, opublikuj /reviewed ponownie albo uruchom Review gate ręcznie z numerem PR-a. Logika żyje w scripts/quality/review-ack.js z testami jednostkowymi w test/review-ack.test.js.
gh pr comment <numer> --body "/reviewed przyjęta poprawka uprawnień, pominięta uwaga o sformułowaniu"Dependabot otwiera cotygodniowe PR-y dla GitHub Actions i deweloperskich zależności npm.
Normalna ścieżka to wydanie:
- Zmerguj zmiany do
maini upewnij się, że CI jest zielone. - Releases → otwórz draft przygotowany przez Release Drafter → Publish release. To tworzy tag
vX.Y.Z. - Actions → uruchomiony właśnie przebieg Deploy to Apps Script → Review deployments → zatwierdź
production. Nic nie jest wypychane przed zatwierdzeniem.
Workflow pobiera wydany tag, uruchamia lint i testy, wypisuje pliki, które clasp wypchnie, wykonuje clasp push --force, zapisuje niezmienną wersję Apps Script nazwaną od taga, a potem weryfikuje żywy projekt: pobiera projekt z powrotem i porównuje go z tagiem (scripts/quality/apps-script-compare.js, ten sam skrypt, którego używa drift check). Czerwony krok weryfikacji oznacza, że push już się odbył, ale projekt się różni; zbadaj to albo cofnij przez deploy_ref. Podsumowanie joba wypisuje wypchnięte pliki, wersję i wynik porównania. Pre-release'y są ignorowane.
Wdrożenie doraźne bez wydania: Actions → Deploy to Apps Script → Run workflow, zostaw Use workflow from na main, zostaw deploy_ref jako main, opcjonalnie zaznacz create_version i zatwierdź tak samo.
Rollback: to samo okno, nadal uruchamiane z main, ale deploy_ref ustawione na poprzedni tag wydania (na przykład v2.9.1). Workflow sprawdza, czy tag istnieje, pobiera go, lintuje i po zatwierdzeniu wypycha te źródła do Apps Script. Zawsze zostawiaj Use workflow from na main: ta lista wybiera definicję workflow, a starsze tagi niosą starsze definicje.
gh workflow run deploy-apps-script.yml --ref main -f deploy_ref=v2.9.1clasp jest przypiętą zależnością deweloperską (package-lock.json), więc uruchomienia lokalne i oba workflow używają tej samej wersji; Dependabot proponuje aktualizacje.
Apps Script drift check działa w każdy poniedziałek (i na żądanie). Pobiera żywy projekt i porównuje go z main przez scripts/quality/apps-script-compare.js (końcowe znaki nowej linii normalizowane po obu stronach: Apps Script zawsze zwraca plik z końcową nową linią, więc zacommitowane źródło bez niej nie jest driftem, a reguła ESLint eol-last trzyma takie pliki poza repozytorium; Version.gs ignorowany, porównywane tylko *.gs i appsscript.json). Jeśli ktoś edytował kod bezpośrednio w edytorze Apps Script, przebieg pada i dołącza patch z różnicami, żeby zmianę dało się wnieść z powrotem do repozytorium.
Notatki wydań żyją na stronie Releases i przygotowuje je automatycznie Release Drafter. Nie ma pliku CHANGELOG.md; opublikowane wydania są changelogiem.
- PR-y są etykietowane na podstawie tytułu, gdy to możliwe.
- Merge PR-a do
mainodświeża draft wydania. feat/newdają podbicie minor; wszystko inne patch.
Publikacja draftu ze strony Releases jest tym, co uruchamia wdrożenie (zob. wyżej). Bazą początkową jest v2.8.0; kolejne wersje trzymają się Semantic Versioning.
MIT.