Przejdź do treści

logintegra-toolbox-cli

Toolbox Logintegra

Wymagania

  • Python 3.14+
  • uv

Instalacja

uv sync

Konfiguracja

Skopiuj przykładowy plik konfiguracyjny do ~/.config/logintegra-toolbox/config.toml:

cp config.example.toml ~/.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:

cp .credentials.example.toml ~/.config/logintegra-toolbox/.credentials.toml
[youtrack]
token = "perm:your-youtrack-token"

[bitbucket]
token = "your-bitbucket-access-token"

Alternatywnie można użyć zmiennych środowiskowych:

export YOUTRACK_TOKEN=perm:your-youtrack-token
export BITBUCKET_TOKEN=your-bitbucket-access-token

Użycie

uv run logintegra [OPCJE] KOMENDA

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 -s scala rekordy w jedną tablicę (potrzebne do grupowania i zliczania), a -r wypisuje czysty tekst zamiast stringa JSON - tego oczekuje slack send na stdin.
  • --arg version służy tylko do nagłówka; podaj tę samą wersję co w verify.
  • Zadania ok są 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_code nie 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

uv run logintegra workflows apollo cut %release.version% --sprint %sprint.name%

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.

docker build -t logintegra-toolbox:latest .

Obraz nie zawiera żadnej konfiguracji ani sekretów:

  • config.toml montuje się do /config (obraz ustawia LOGINTEGRA_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 typu password.
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

uv run ruff format .
uv run ruff check .

Sprawdzanie typów

uv run mypy src

Testy

uv run pytest

Dodawanie zależności

Zależność produkcyjna:

uv add <nazwa-pakietu>

Zależność dev:

uv add --group dev <nazwa-pakietu>

Ostatnia zmiana: 2026-07-22 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e