Integracja z GitHub
0 Wprowadzenie
Integracja GitHub to dodatek, który można dodać do dowolnego z trzech planów Easy Redmine.
Celem wtyczki jest agregacja ważnych danych z GitHub w Easy Redmine, aby pomóc w raportowaniu, ocenie i prezentacji działań programistycznych, wspierając w ten sposób podejmowanie decyzji ze strony interesariuszy, którzy inwestują w projekty i procesy rozwoju oprogramowania Spółka.
Jego możliwości obejmują bardzo proste początkowe połączenie z Twoją instancją GitHub (zarówno w wersji samoobsługowej, jak i w chmurze). Po nawiązaniu połączenia Easy Redmine pokaże najważniejsze elementy z GitHub w konfigurowalnych i filtrowalnych listach (podobnie jak lista zadań). Te podmioty to:
- Repozytoria
- Wyciągnij żądania
- Zobowiązuje się
- Testy
w tym ich najważniejsze atrybuty.
Kluczowym elementem integracji jest to, że Easy Redmine NIE kopiuje fizycznie repozytoriów. Kod pozostaje w GitHub.
1 Nawiązywanie połączenia
Po pierwsze, musisz mieć token dostępu od użytkownika w GitHub, z odpowiednimi uprawnieniami.
- Wybierz użytkownika, za pośrednictwem którego Easy Redmine będzie uzyskiwać dostęp do GitHub. Może to być specjalny użytkownik, przez którego nikt się nie loguje, na przykład er_integrator
- Zaloguj się do GitHub przez tego użytkownika
- Kliknij awatar >> Ustawienia
- Ustawienia programisty
- Osobiste tokeny dostępu
- Wygeneruj nowy token
- Musisz zezwolić na te zakresy
- repo (Pełna kontrola prywatnych repozytoriów)
- admin:repo_hook (Pełna kontrola hooków repozytorium)
- użytkownik (Aktualizuj WSZYSTKIE dane użytkownika) - Skopiuj token
Teraz możesz przejść do Easy Redmine i wprowadzić ważne informacje - Przejdź do Admin >> Integracja z Git >> Znajdź Dostępne integracje i uderz Dodaj
- Nadaj swojemu połączeniu nazwę, wprowadź adres URL i wygenerowany wcześniej token dostępu.
Uwaga: W przypadku chmury, np. https://github.com/robogithub-easy , po prostu wpisz https://github.com/ bez podadresu. Nie musisz się martwić, możesz zobaczyć tylko projekty, które widzi użytkownik z tokenem dostępu. Jeśli ustawisz wszystkie swoje projekty jako prywatne, nikt inny nie będzie mógł ich zobaczyć.
- Zapisz
- Otóż to! Połączenie jest gotowe.
Cała reszta odbywa się automatycznie w tle. W szczególności
- Easy Redmine pobiera wszystkie projekty/repozytoria, których członkiem jest użytkownik z tokenem dostępu
- W tych repozytoriach tworzone są webhooki =>, aby informacje o nowych zatwierdzeniach, żądaniach pull i testach były wysyłane do Easy Redmine
1.1 Rozwiązywanie problemów z połączeniem
Problem A
Nie widzę żadnego repozytorium z tej instancji GitHub
Ze względu na nieprzewidywalne okoliczności może się zdarzyć, że powyższe operacje nie zostaną przeprowadzone pomyślnie. W rezultacie możesz nie widzieć żadnego repozytorium z tej instancji GitHub w Easy Redmine.
W takim przypadku możesz ręcznie zaimportować repozytoria za pomocą kilku kliknięć.
- Przejdź do Admin >> Integracja z Git >> Skonfigurowane integracje >> Kliknij nazwę
- W menu bocznym kliknij Dodaj repozytorium
- Znajdź repozytorium
- Po jego wybraniu pozostałe pola zostaną wypełnione automatycznie
- Kliknij Zapisz
Repozytorium zostało dodane
Problem B
Znaleziono repozytoria, ale moje nowe zatwierdzenia, żądania ściągnięcia i testy nie są dodawane do Easy Redmine
Nowe dane z GitHub są wysyłane do Easy Redmine za pośrednictwem webhooków skonfigurowanych w GitHub. W normalnych warunkach są tworzone automatycznie. Możesz to sprawdzić w swoim projekcie GitHub >> Ustawienia >> Webhooks
Jeśli nie ma webhooka z linkiem do Twojej aplikacji, będziesz musiał go utworzyć. Znowu jest to prosta operacja.
- Przejdź do Admin >> Integracja z Git >> Skonfigurowane integracje >> Kliknij nazwę
- W menu bocznym kliknij Repozytoria
- Kliknij imię jednego
- Kliknij na Zarejestruj wszystkie integracje
Wymusi to ręczne utworzenie webhooka we właściwej formie.
Jeśli webhook istnieje, ale zawiera informację o błędzie, sprawdź komunikat o błędzie i spróbuj rozwiązać problem.
2 Odwołujące się słowa kluczowe
Teraz, gdy ogólne połączenie jest skonfigurowane, masz już informacje z GitHub w Easy Redmine i możesz je wykorzystać. Aby jednak w pełni wykorzystać integrację, jest jeszcze kilka ustawień. Niektóre są już ustawione i możesz je tylko sprawdzić.
Możliwe jest łączenie poszczególnych zatwierdzeń lub ściąganie żądań do określonych zadań, a nawet rejestrowanie czasu w ten sposób bez konieczności odwiedzania Easy Redmine. Odbywa się to przez tzw odniesienia do słów kluczowych. Gdy użyjesz ich w komunikacie zatwierdzenia lub nazwie żądania ściągnięcia w połączeniu z identyfikatorem zadania, utworzy link między zadaniem a elementem GitHub. Najczęstsze przykłady to nr ref. #1234 or zamyka #1234
W większości przypadków znajdziesz kilka wstępnie ustawionych słów kluczowych. Oto jak z nimi pracować.
- Przejdź do menu globalnego >> Integracja z Gitem >> Referencje
- Utwórz lub edytuj referencję
- Cały formularz zawiera podpowiedzi ułatwiające poruszanie się po nich
Najważniejsze zasady do zapamiętania to:
- Zadanie musi być zidentyfikowane w postaci #ID , np. #1234
- Czas logowania (jeśli jest dozwolony) jest zawsze wprowadzany jako @XhYm, np. @1h30m
- W przypadku zatwierdzeń słowa kluczowe odniesienia należy wprowadzić w komunikat dotyczący zatwierdzenia
- W przypadku pull requestów słowa kluczowe odniesienia należy wpisać w Nazwa żądania ściągnięcia
Mapowanie 3 użytkowników
Ponieważ mamy do czynienia z integracją dwóch różnych aplikacji, każda z nich ma inny zestaw użytkowników. Wszystkie atrybuty użytkownika w podmiotach powiązanych z GitHub (autor zatwierdzenia, recenzent na żądanie ściągnięcia itp.) W Easy Redmine + spędzony czas zalogowany za pomocą słów kluczowych odwołujących się, powinny być połączone z prawdziwymi użytkownikami. W jaki sposób użytkownicy z GitHub są mapowani do Easy Redmine?
Nic naukowego tutaj, użytkownicy są po prostu mapowani za pośrednictwem poczty e-mail w obu profilach użytkowników. Upewnij się, że Twoi programiści mają identyczne e-maile zarówno w GitHub, jak i Easy Redmine.
Jeśli z jakiegoś powodu jeden użytkownik nie może ujednolicić wiadomości e-mail w obu aplikacjach, istnieje możliwość wprowadzenia dodatkowego adresu e-mail w Easy Redmine w profilu użytkownika -> wprowadź tutaj adres e-mail Github.
4 Jak to działa
Wreszcie dochodzimy do zabawnej części. Co integracja faktycznie daje użytkownikom. Uzyskaj dostęp do strony głównej/panelu integracji Git poprzez menu globalne (w prawym górnym rogu) w sekcji Dodatki.
Znajdziesz dostosowywalną stronę w stanie domyślnym, którą możesz później dostosować do swoich potrzeb.
Zawiera również menu do wyświetlania jednostek lub wprowadzania ustawień. Jak wspomniano we wstępie, Easy Redmine gromadzi i wyświetla 4 kluczowe podmioty z GitHub. Przyjrzyjmy się każdemu z nich.
4.1 Repozytoria
Lista repozytoriów jest funkcjonalnie najmniej interesująca, choć naprawdę potrzebna. Przydatny filtr, o którym warto wspomnieć, to Usługi, którego użyjesz, jeśli masz połączone różne instancje GitHub i musisz przeszukać tylko niektóre z nich.
Szczegóły repozytorium
Uwagi:
- (Nie-)Zarejestruj wszystkie integracje zostały opisane w rozdziale 1.1. Utworzy/usunie webhooki w projekcie GitHub.
- Edytuj - ręcznie zmienić niektóre atrybuty. Nie ma innego powodu niż zaawansowane debugowanie, aby edytować dowolne atrybuty repozytorium w Easy Redmine.
- Synchronizować - pobiera wszystkie aktualne dane z repozytorium.
- Wyciągnij żądania - wyświetla wszystkie pull requesty w tym repozytorium.
- Wybierz szablon sekwencji - wciąż w fazie rozwoju, daj nam więcej czasu na dopracowanie tego solidnego narzędzia.
4.2 Żądania ściągnięcia (żądania kodu)
Powinniśmy wyjaśnić, dlaczego istnieją dwie nazwy. Prośba o pociągnięcie to termin używany w serwisie GitHub. Inne narzędzia mają na to inne nazwy, na przykład Prośba o scalenie. Mechanizm integracji naszego narzędzia jest napisany w sposób ogólny, dzięki czemu możemy rozszerzyć wsparcie na inne platformy Git. Dlatego w aplikacji i obrazach możesz znaleźć etykietę Prośba o kod, który jest ogólnym terminem, który można zastosować do żądań ściągania lub żądań scalania.
Pull request to bogata jednostka (przechowuje wszystkie ważne atrybuty), która pozwala tworzyć ładne zestawienia, raporty, a nawet wykresy nad nimi bezpośrednio w Easy Redmine.
Szczegóły żądania ściągnięcia
Uwagi:
- Nazwa pull requesta zawiera odwołujące się słowo kluczowe "refs", po którym następuje ID zadania z hashem #765 - dlatego zostało powiązane z zadaniem 765
- Kliknięcie na Synchronizować zaktualizuje wszystkie dane tego PR z GitHub
- Wszystkie atrybuty mogą być wyświetlane na liście żądań ściągnięcia
- Wszystkie atrybuty z wyjątkiem SHA mogą być używane jako filtry na liście/raporcie/wykresie pull requestów
- Lista pull request zawiera również atrybuty testów (CI/CD) z nią związanych, przede wszystkim - Status testu
4.3 Zobowiązania
Podobnie jak w przypadku pull requestów, lista zatwierdzeń zapewnia również ogromne możliwości raportowania. Lista zatwierdzenia zawiera również atrybuty z testów.
Commit nie ma własnego widoku szczegółów w Easy Redmine. Po prostu nie ma takiej potrzeby. Klikając na URL (lub SHA), zostaniesz przekierowany do jego szczegółów w GitHub.
Testy 4.4
Zostały one wymienione w odniesieniu do ww. podmiotów. Testy mają również własną listę do generowania różnych raportów. Prawdopodobnie najczęstszym zastosowaniem będzie podgląd na żywo testów w krytycznych repozytoriach, takich jak kandydaci do wydania.
Testy również nie posiadają własnego widoku szczegółów, kliknięcie przeniesie Cię do GitHub.
4.5 Synergia – widok z zadania
Przyjrzyjmy się, jak to wszystko idzie w parze.
1 Ogólny stan encji GitHub związanych z tym zadaniem. Może zawierać różne kombinacje kolorów (czerwony, pomarańczowy, zielony) oraz ikon (znacznik wyboru, krzyżyk). Najlepszy to oczywiście zielony haczyk w zielonej ramce
Kombinacja zależy od statusu żądań ściągnięcia i wyników testów związanych z zatwierdzeniami i żądaniami ściągnięcia. Jego celem jest pokazanie na pierwszy rzut oka, jak postępuje „techniczny” postęp tego zadania, przydatne zwłaszcza dla QA lub kierowników dostaw.
2 Nazwa repozytorium(ów), do których zostały wprowadzone zmiany dotyczące tego zadania. Klikając w link zostaniesz przekierowany do listy tych zatwierdzeń.
3 Nazwa żądań ściągnięcia odnoszących się do tego zadania. Klikając na niego, zostaniesz przekierowany do szczegółów PR w Easy Redmine.
W przypadku, gdy istnieją tylko zatwierdzenia odnoszące się do tego zadania, ale brakuje żądania ściągnięcia, ta wartość jest pusta.
4 Stan każdego żądania ściągnięcia. Klikając go, zostaniesz przekierowany do szczegółów żądania ściągnięcia w GitHub.
W przypadku, gdy istnieją tylko zatwierdzenia odnoszące się do tego zadania, ale brakuje żądania ściągnięcia, ta wartość jest pusta.
5 Wynik ostatniego uruchomienia testowego w żądaniu ściągnięcia. Klikając na niego zostaniesz przekierowany do GitHub. Nie można go kliknąć w Autor nieznany status (test nie istnieje).
W przypadku, gdy istnieją tylko zatwierdzenia odnoszące się do tego zadania, ale brakuje żądania ściągnięcia, wartość pokazuje wynik ostatniego testu uruchomionego przy ostatnim zatwierdzeniu.
6 Uruchom test ręcznie - przeniesie Cię do GitHub.
7 Kliknij, aby utworzyć żądanie ściągnięcia. Przydatne, gdy masz tylko zestaw zatwierdzeń, ale brakuje Ci PR (przenosi Cię do GitHub).
4.6 Utwórz oddział z zadania
Niektórym użytkownikom przydatne jest tworzenie gałęzi bezpośrednio z zadania.
Przycisk znajduje się w ogólne menu w szczegółach zadania
Wybierz repozytorium w polu autouzupełniania. Nazwa oddziału jest wstępnie wypełniona identyfikatorem zadania i tematem, ale możesz to zmienić. Gałąź źródłowa jest wstępnie wypełniana przez mistrz
Gałąź zobaczysz jako tag w sekcji integracji Git w zadaniu. Jest klikalny i prowadzi do oddziału w GitHub.
5 uprawnień
Obecnie istnieją dwa uprawnienia.
- Widok — dostęp do dodatku z menu globalnego
- Zarządzaj - edytuj dashboard
Konfiguracja globalna jest dostępna tylko dla administratora Easy Redmine.