Atlassian (Jira i Confluence)

Co to robi

Atlassian łączy Speedwave z Jirą i Confluence. Speedwave potrafi wyszukiwać i aktualizować zgłoszenia w Jirze, prowadzić je przez kolejne etapy procesu, dołączać do nich pliki z projektu, obsługiwać tablice Agile i sprinty, a po stronie Confluence czytać oraz zapisywać strony, komentarze i etykiety. Działa to tylko z Atlassian Cloud. Data Center i Server nie są obsługiwane.

Z czego się składa

Atlassian to wbudowany worker z osobnym kontenerem, który włączasz oddzielnie dla każdego projektu z poziomu aplikacji Desktop. Opiera się na trzech danych uwierzytelniających: adresie URL witryny, adresie e-mail i tokenie API. Leżą one na dysku i są podpięte do workera wyłącznie do odczytu. Tak samo, tylko do odczytu, podpięty jest folder projektu pod ścieżką /workspace, z którego worker czyta pliki wysyłane jako załączniki. Dwie opcjonalne listy dozwolonych wartości, klucze projektów Jira oraz klucze przestrzeni Confluence, zawężają to, których projektów i przestrzeni worker może dotknąć.

Jak to działa

Worker uwierzytelnia się jako prawdziwe konto Atlassian i dociera tam, dokąd dociera samo konto, i właśnie dlatego listy dozwolonych wartości mają takie znaczenie. Kiedy je uzupełnisz, każda operacja poza wymienionymi projektami czy przestrzeniami zostaje odrzucona. Bez danych uwierzytelniających lub przy błędnych danych worker wpada w stan „nieskonfigurowany”: nadal chodzi, ale każde wywołanie narzędzia zwraca zrozumiały błąd, dopóki tego nie naprawisz.

Żądanie idzie od Speedwave przez Tool Gateway, który nie trzyma żadnych tokenów, do workera, a ten podpina swój folder z danymi uwierzytelniającymi tylko do odczytu i łączy się wprost z REST API Jira i Confluence Cloud.

Co potrafi Speedwave

Worker udostępnia 35 narzędzi: 22 dla Jiry i 13 dla Confluence. Jedno jest destrukcyjne: deleteAttachment usuwa załącznik bezpowrotnie. Cała reszta tylko tworzy, czyta lub aktualizuje.

Jira

Narzędzie	Co robi
`searchIssues`	Wyszukuje zgłoszenia przy użyciu JQL, wyniki dzieli na strony kursorem (50 na stronę, do 100).
`getIssue`	Pobiera pojedyncze zgłoszenie po kluczu lub numerycznym ID.
`createIssue`	Zakłada zgłoszenie z tytułem, typem, opisem, priorytetem, etykietami i osobą przypisaną.
`updateIssue`	Zmienia tytuł, opis, priorytet lub etykiety zgłoszenia.
`getTransitions`	Podaje przejścia w procesie, jakie są dostępne dla zgłoszenia.
`transitionIssue`	Przeprowadza zgłoszenie przez przejście w procesie.
`assignIssue`	Przypisuje zgłoszenie do kogoś lub zdejmuje przypisanie.
`getMyself`	Zwraca konto Atlassian, jako które uwierzytelnia się worker.
`addAttachment`	Dołącza plik do zgłoszenia: worker czyta go ze ścieżki pod `/workspace` i przesyła prosto do Jiry, więc jedynym limitem rozmiaru jest ten w twojej Jirze.
`deleteAttachment`	Usuwa załącznik po ID, bezpowrotnie. Odmawia działania, gdy ustawiona jest lista dozwolonych projektów Jira, bo samego ID załącznika nie da się z nią zestawić.
`addComment`	Dopisuje komentarz do zgłoszenia.
`getComments`	Podaje komentarze przy zgłoszeniu.
`addWorklog`	Rejestruje czas poświęcony na zgłoszenie.
`listProjects`	Podaje projekty Jira, można je filtrować po nazwie lub kluczu.
`getProject`	Pobiera pojedynczy projekt po kluczu lub ID.
`listIssueTypes`	Podaje typy zgłoszeń dostępne w projekcie.
`listBoards`	Podaje tablice Agile, można je filtrować po projekcie lub nazwie.
`getBoard`	Pobiera pojedynczą tablicę Agile po ID.
`getBoardConfiguration`	Pobiera konfigurację filtrów i kolumn tablicy.
`listSprints`	Podaje sprinty na tablicy, opcjonalnie zawężone po statusie.
`getSprint`	Pobiera pojedynczy sprint po ID.
`moveIssuesToSprint`	Wrzuca do sprintu maksymalnie 50 zgłoszeń na jedno wywołanie.

Confluence

Narzędzie	Co robi
`searchPages`	Wyszukuje strony przy użyciu CQL, płaski limit wyników (domyślnie 25, do 100).
`getPage`	Pobiera stronę po ID, opcjonalnie wraz z jej treścią.
`getPageByTitle`	Odnajduje stronę po dokładnym tytule w obrębie przestrzeni.
`createPage`	Zakłada stronę, treść jako zwykły tekst albo XHTML w formacie storage.
`updatePage`	Zmienia tytuł lub treść strony i sam podbija numer wersji.
`getPageChildren`	Podaje strony podrzędne leżące bezpośrednio pod daną stroną.
`addPageComment`	Dopisuje komentarz w stopce strony.
`getPageComments`	Podaje komentarze ze stopki strony.
`addPageLabels`	Dokłada do strony jedną etykietę lub więcej.
`getPageLabels`	Podaje etykiety strony.
`listAttachments`	Podaje załączniki strony (same metadane, bez pobierania).
`listSpaces`	Podaje przestrzenie Confluence, opcjonalnie zawężone po kluczu.
`getSpace`	Pobiera pojedynczą przestrzeń po kluczu.

Jako treść możesz przekazać zwykły tekst, który worker sam przełoży, albo gotową strukturę: ADF dla Jiry, a dla Confluence XHTML w formacie storage. Numeryczne ID zgłoszenia w Jirze, na przykład 10042, odbija się od listy dozwolonych wartości, dopóki nie rozwiniesz go do klucza w rodzaju PROJ-123.

Skonfiguruj to

Utwórz token API na id.atlassian.com/manage-profile/security/api-tokens.
W aplikacji Desktop otwórz listę integracji projektu i wybierz Atlassian.
Podaj swój Atlassian site URL (https://twoja-domena.atlassian.net), swój Account email oraz API token.
Opcjonalnie uzupełnij listy dozwolonych wartości Jira project keys i Confluence space keys. Zostaw je puste, żeby dopuścić wszystkie projekty i przestrzenie, do których konto ma dostęp.
Zapisz.

Ogólny przebieg włączania dowolnej integracji i sprawdzania, czy działa, znajdziesz na stronie Podłącz integrację.

Gdy coś się nie uda, worker tłumaczy odpowiedź na zrozumiałą wskazówkę: 401/403 to błędne dane uwierzytelniające albo brak uprawnień, 404 znaczy, że elementu nie znaleziono, 429 to przekroczony limit zapytań, a 5xx to błąd po stronie serwera Atlassian. Odczyty ponawiają się same, zapisy worker powtarza tylko przy błędzie 429 i nigdy przy 5xx, żeby nie narazić się na podwojone zgłoszenie czy komentarz.

Granice bezpieczeństwa

Worker chodzi jako użytkownik bez uprawnień administratora, z odebranymi wszystkimi uprawnieniami Linuksa (cap_drop: ALL), zablokowaną eskalacją uprawnień (no-new-privileges) i systemem plików tylko do odczytu, a oba punkty podpięcia, folder z danymi uwierzytelniającymi i folder projektu pod /workspace, też są tylko do odczytu. Ścieżka załącznika, która wychodzi poza /workspace przez .. albo dowiązanie symboliczne, zostaje odrzucona, więc workera nie da się namówić na wysłanie jego własnych plików z tokenami. Sięga jedynie do wskazanej przez ciebie witryny Atlassian Cloud i tylko tak daleko, jak pozwolą uzupełnione listy dozwolonych wartości. Przekierowania są wyłączone, żeby nagłówek Authorization nie mógł wyciec na inny host, a każdy komunikat błędu, który zdradziłby dane uwierzytelniające, zostaje wcześniej oczyszczony. Ani Speedwave, ani Tool Gateway nigdy nie widzą adresu URL witryny, e-maila czy tokenu API. O tym, jak ta izolacja trzyma się w każdej integracji, przeczytasz na stronie Jak obsługiwane są dane uwierzytelniające.