logintegra-toolbox-cli¶
Toolbox Logintegra
Wymagania¶
- Python 3.14+
- uv
Instalacja¶
Konfiguracja¶
Skopiuj przykładowy plik konfiguracyjny do ~/.config/logintegra-toolbox/config.toml:
[youtrack]
url = "https://youtrack.example.com"
[bitbucket]
url = "https://api.bitbucket.org/2.0"
username = "[email protected]"
[slack]
url = "https://slack.com/api"
Dane uwierzytelniające¶
Skopiuj przykładowy plik credentials do ~/.config/logintegra-toolbox/.credentials.toml:
Alternatywnie można użyć zmiennych środowiskowych:
Użycie¶
YouTrack¶
# Sprawdź połączenie
logintegra youtrack ping
# Wylistuj issues pasujące do zapytania
logintegra youtrack issues "Sprint is wombaty-49"
Bitbucket¶
# Sprawdź połączenie
logintegra bitbucket ping
# Wylistuj pull requesty (domyślnie OPEN)
logintegra bitbucket prs apollo
logintegra bitbucket prs apollo --state MERGED --target develop --limit 50
# Wylistuj branche pasujące do wzorca
logintegra bitbucket branches apollo --filter release-
# Wyciągnij klucze zadań YouTrack z pull requesta (tytuł, branch, opis, commity)
logintegra bitbucket pr-issues apollo 42 --project A
# {"key":"A-18301","pr_id":42,"repo":"apollo","sources":["title","branch","commit"]}
Workspace pobierany jest z bitbucket.workspace w konfiguracji; można go nadpisać opcją
--workspace.
Pole sources mówi, skąd pochodzi dany klucz. Klucz znaleziony wyłącznie w nazwie brancha
jest słabszą przesłanką niż klucz z commita - dlatego narzędzie nie zgaduje, tylko raportuje
pochodzenie.
YouTrack - zmiany na zadaniach¶
Polecenia zmieniające dane przyjmują listę zadań z argumentów lub ze stdin (klucze albo
NDJSON) i wspierają --dry-run.
# Ustaw Release na wskazanych zadaniach
logintegra youtrack set-release release-4.159.0 A-18301 A-18302
# Tagi (needs-update, needs:manual-config)
logintegra youtrack tag needs-update A-18301
logintegra youtrack tag needs-update A-18301 --remove
# Dowolne polecenie YouTracka
logintegra youtrack command "State Fixed" A-18301 --comment "Wydane w 4.159.0"
# Komentarz (tekst z argumentu albo z pipe'a)
logintegra youtrack comment A-18301 "Uwagi do procesu"
Najpierw --dry-run. Pokazuje dokładnie, co i na jakich zadaniach zostałoby zmienione,
i nie wywołuje API (nie wymaga nawet tokenu):
logintegra youtrack set-release release-4.159.0 A-18301 --dry-run
# {"key":"A-18301","command":"Release release-4.159.0","applied":false,"dry_run":true}
Pusty strumień na wejściu nie robi nic i wypisuje ostrzeżenie - nie jest traktowany jako sukces.
Release - weryfikacja odcięcia¶
Porównuje zadania wynikające z kodu (commity, które są na branchu release, a nie były w
poprzednim wydaniu) z zadaniami oznaczonymi Release w YouTracku.
logintegra release verify 4.159.0 \
--repo apollo --repo apollo-frontend --repo msc \
--previous release-4.158.0 --project A
Odcięcie obejmuje kilka repozytoriów (backend, frontend, mikroserwisy) - --repo powtarza się dla
każdego z nich. Wszystkie repozytoria trzymają tę samą konwencję branchy, więc --branch
i --previous są wspólne.
Repozytoria są uzgadniane razem, w jednym przebiegu, a nie osobno. To jest istotne: zadanie
zrobione wyłącznie na froncie ma kod w odcięciu, więc jest ok. Trzy osobne uruchomienia
verify (po jednym na repo) pokazałyby je jako no_code w backendzie i ok na froncie -
sklejenie takich raportów daje fałszywe problemy.
Repo, które nie ma brancha release (np. mikroserwis nieodcinany w tym wydaniu), zwraca z Bitbucketa
404 - takie repo jest pomijane i nie przerywa weryfikacji. Pomięcie trafia na stderr jako
ostrzeżenie, bo literówka w --repo wygląda identycznie jak repo bez zmian: w obu przypadkach
repo nie wnosi kodu, a jego zadania mogą przez to wyjść jako no_code. Warto zerknąć na
ostrzeżenia, zanim uzna się raport za wiarygodny.
Każdy rekord ma status:
| status | znaczenie |
|---|---|
ok |
zadanie jest i w kodzie (w dowolnym repo odcięcia), i oznaczone Release: release-4.159.0 |
missing_release |
kod jest w odcięciu, ale zadanie nie ma ustawionego Release |
no_code |
zadanie ma ustawiony Release, ale nie ma commitów w żadnym repo odcięcia |
unknown_issue |
klucz z commita nie istnieje w YouTracku (literówka) |
Pole repos mówi, w których repozytoriach znaleziono kod, a commits to suma commitów ze
wszystkich repozytoriów:
# gdzie szukać kodu zadań bez ustawionego Release
logintegra release verify 4.159.0 \
--repo apollo-backend --repo apollo-frontend --repo microservice-courier --repo infokiosk \
--previous release-4.158.0 \
| jq -r 'select(.status == "missing_release") | [.key, (.repos | join(",")), .summary] | @tsv'
# tylko problemy
logintegra release verify 4.159.0 \
--repo apollo --repo apollo-frontend --repo msc \
--previous release-4.158.0 \
| jq 'select(.status != "ok")'
Polecenie jest wyłącznie do odczytu i można je uruchamiać wielokrotnie.
Wynik można podać wprost do poprawki - to zastępuje ręczne wklejanie opisu PR do komentarza
i ustawianie Release klikaniem:
logintegra release verify 4.159.0 \
--repo apollo --repo apollo-frontend --repo msc \
--previous release-4.158.0 --project A \
| jq -r 'select(.status == "missing_release").key' \
| logintegra youtrack set-release release-4.159.0 --dry-run
Raport na Slacku¶
Wynik release verify to NDJSON, więc raport dla ludzi składa się filtrem jq
contrib/slack-verify.jq i wysyła przez logintegra slack send:
uv run logintegra release verify 4.163.0 \
--repo apollo-backend --repo apollo-frontend \
--repo microservice-courier --repo infokiosk \
--workspace logintegraspzoo --previous release-4.162.0 \
| jq -sr --arg version "4.163.0" -f contrib/slack-verify.jq \
| uv run logintegra slack send 'apollo-cut'
Efekt:
*Weryfikacja wydania 4.163.0* – 42 ok, 4 problemy
:red_circle: *Nieznane zgłoszenia* (1)
• `A-18999` _bez tytułu_ _(infokiosk)_
:large_orange_circle: *Brak wersji w YouTrack* (2)
• `A-18301` Poprawka NPE w wyszukiwaniu przewoźnika _(apollo-backend, apollo-frontend)_
• `A-18302` Ponawianie wysyłki w kliencie SMTP _(microservice-courier)_
:large_blue_circle: *Brak kodu w cutcie* (1)
• `A-18310` Aktualizacja dokumentacji
Uwagi:
jq -sscala rekordy w jedną tablicę (potrzebne do grupowania i zliczania), a-rwypisuje czysty tekst zamiast stringa JSON - tego oczekujeslack sendna stdin.--arg versionsłuży tylko do nagłówka; podaj tę samą wersję co wverify.- Zadania
oksą zliczane, ale nie wypisywane - to większość wydania i nic nie wnoszą do przeglądu. Gdy nie ma żadnych problemów, wiadomość to:white_check_mark: Wszystko się zgadza., więc pipeline jest bezpieczny do uruchamiania cyklicznie. - W nawiasie na końcu linii są repozytoria, w których znaleziono kod zadania - przy czterech repo
to pierwsza rzecz, o którą pyta osoba poprawiająca.
no_codenie ma kodu nigdzie, więc tam nawias się nie pojawia. - Nie dokładaj tu
--strict: kod wyjścia 1 przerwałby pipeline, zanim wiadomość trafi na Slacka. - Kolejność statusów jest ta sama co w
STATUS_ORDER(release/reconcile.py) - najpierw to, co wymaga człowieka.
Output i pipowanie¶
CLI jest zaprojektowane wokół kompozycji w stylu Unix. Każde polecenie produkujące dane zapisuje NDJSON (newline-delimited JSON) na stdout.
Dzięki temu każde polecenie można wpiąć w inny program lub inne polecenie logintegra:
# Ładne wyświetlenie przez jq
logintegra youtrack issues "Sprint: wombaty-49" | jq .
# Wyciągnięcie konkretnego pola
logintegra youtrack issues "Sprint: wombaty-49" | jq -r '.idReadable'
# Filtrowanie w locie
logintegra youtrack issues "Sprint: wombaty-49" | jq 'select(.summary | test("login"))'
# Pipe do innego polecenia logintegra
logintegra youtrack issues "Sprint: wombaty-49" | logintegra slack notify channel-1
TeamCity¶
Narzędzie dobrze nadaje się do kroków buildowych w TeamCity.
Przykładowy krok - cut
Przykładowy krok - weryfikacja przed deployem:
COUNT=$(uv run logintegra youtrack issues "Sprint: %sprint.name% #Unresolved" | jq -s 'length')
if [ "$COUNT" -gt 0 ]; then
echo "##teamcity[buildProblem description='Są nierozwiązane issues: '"$COUNT"']"
exit 1
fi
Przykładowy krok - weryfikacja odcięcia (--strict przerywa build):
uv run logintegra release verify %release.version% \
--repo apollo --repo apollo-frontend --repo msc --previous release-%previous.version% --project A --strict
Wymagania na agencie: Python 3.14+ oraz uv muszą być zainstalowane.
Docker¶
Zamiast instalować Pythona i uv na agencie, można uruchamiać CLI z obrazu. Obraz zawiera też
jq oraz filtr contrib/slack-verify.jq (pod /opt/logintegra/contrib),
więc całe pipeline'y z tego README działają w środku bez dokładania czegokolwiek.
Obraz nie zawiera żadnej konfiguracji ani sekretów:
config.tomlmontuje się do/config(obraz ustawiaLOGINTEGRA_CONFIG_DIR=/config). Plik nie ma sekretów - są w nim tylko adresy URL, workspace i login.- Tokeny przekazuje się zmiennymi środowiskowymi:
YOUTRACK_TOKEN,BITBUCKET_TOKEN,SLACK_TOKEN. W TeamCity trzymaj je jako parametry typupassword.
docker run --rm \
-v /opt/teamcity/logintegra:/config:ro \
-e YOUTRACK_TOKEN -e BITBUCKET_TOKEN -e SLACK_TOKEN \
logintegra-toolbox:latest youtrack issues "Sprint: wombaty-49"
ENTRYPOINT to samo logintegra, więc argumenty podaje się wprost, bez powtarzania nazwy
polecenia. Gdy potrzebny jest pełny pipeline z jq, uruchom powłokę:
docker run --rm -v /opt/teamcity/logintegra:/config:ro \
-e BITBUCKET_TOKEN -e YOUTRACK_TOKEN -e SLACK_TOKEN \
--entrypoint sh logintegra-toolbox:latest -c '
logintegra release verify %release.version% \
--repo apollo-backend --repo apollo-frontend \
--repo microservice-courier --repo infokiosk \
--workspace logintegraspzoo --previous release-%previous.version% \
| jq -sr --arg version "%release.version%" -f /opt/logintegra/contrib/slack-verify.jq \
| logintegra slack send apollo-cut'
W kroku Docker w TeamCity wystarczy podać obraz i argumenty - TeamCity sam montuje katalog
roboczy i potrafi uruchomić kontener pod UID agenta. Obraz to obsługuje: konfiguracja jest
szukana w LOGINTEGRA_CONFIG_DIR, a nie w $HOME, więc działa pod dowolnym użytkownikiem.
Sekcja [slack] (jak każda inna) jest opcjonalna - krok, który jej nie używa, nie potrzebuje jej
w config.toml ani tokenu.
Inne¶
Formatowanie i linting¶
Sprawdzanie typów¶
Testy¶
Dodawanie zależności¶
Zależność produkcyjna:
Zależność dev:
Ostatnia zmiana: 2026-07-22 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e