GitHub-integration

0 Inledning

GitHub Integration är ett tillägg som kan läggas till någon av de tre Easy Redmine-planerna.

Syftet med pluginet är att aggregera viktig data från GitHub i Easy Redmine för att hjälpa till med rapportering, utvärdering och presentation av utvecklingsaktiviteter och på så sätt stödja beslutsfattande från sidan av intressenter som är investerade i mjukvaruutvecklingsprojekt och processer av företaget.

Dess möjligheter inkluderar en mycket enkel initial anslutning med din GitHub-instans (både självvärd eller molnversioner). När anslutningen är upprättad kommer Easy Redmine att visa de mest avgörande objekten från GitHub i konfigurerbara och filtrerbara listor (liknar en uppgiftslista). Dessa enheter är:

arkiv
Dra förfrågningar
Begår
Tester

inklusive deras viktigaste egenskaper.

En viktig del av integrationen är att Easy Redmine INTE kopierar arkiven fysiskt. Koden finns kvar i GitHub.

1 Upprätta anslutning

För det första måste du ha en åtkomsttoken från en användare i GitHub, med rätt behörighet.

Välj en användare via vilken Easy Redmine kommer att få åtkomst till GitHub. Detta kan vara en speciell användare som ingen person loggar av, t.ex. er_integrator
Logga in på GitHub av denna användare
Klicka på avataren >> Inställningar
Utvecklarinställningar
Personliga åtkomsttokens
Generera ny token
Du måste tillåta dessa omfattningar
- repo (Full kontroll över privata förvar)
- admin:repo_hook (Full kontroll över förvarskrokar)
- användare (Uppdatera ALLA användardata)
Kopiera token

Nu kan du gå till Easy Redmine och ange den viktiga informationen
Gå till Admin >> Git integration >> Hitta Tillgängliga integrationer och slå Lägg till
Ge din anslutning ett namn, ange URL:en och åtkomsttoken du genererade tidigare.
Notera: Vid moln, t.ex https://github.com/robogithub-easy , skriv bara in https://github.com/ utan sub-url. Du behöver inte oroa dig, du kan bara se projekt som användaren med åtkomsttoken kan se. Om du ställer in alla dina projekt som privata kommer ingen annan att kunna se dem.
Save
Det är allt! Anslutning är gjord.

Allt annat görs automatiskt i bakgrunden. Särskilt

Easy Redmine hämtar alla projekt/förråd som användaren med åtkomsttoken är medlem i
I dessa repositories skapas webhooks => så att info om nya commits, pull-förfrågningar och tester skickas till Easy Redmine

1.1 Anslutningsfelsökning

Problem A
Jag ser inget arkiv från denna GitHub-instans
På grund av oförutsebara omständigheter kan det hända att ovannämnda operationer inte kommer att genomföras framgångsrikt. Som ett resultat kanske du inte ser något arkiv från denna GitHub-instans i Easy Redmine.

I sådana fall kan du importera arkiven manuellt, med bara några få klick.

Gå till Admin >> Git integration >> Konfigurerade integrationer >> Klicka på namnet
Klicka på i sidomenyn Lägg till förråd
Hitta arkivet
När du har valt det kommer andra fält att fyllas i automatiskt
Klicka Save
Repository läggs till

Problem B
Lagrar hittades, men mina nya commits, pull-förfrågningar och tester läggs inte till i Easy Redmine
Ny data från GitHub skickas till Easy Redmine via webhooks konfigurerade i GitHub. Under normala omständigheter skapas de automatiskt. Du kan verifiera detta i ditt GitHub-projekt >> Inställningar >> Webhooks

Om det inte finns någon webhook med länken till din ansökan måste du skapa den. Återigen, detta är en enkel operation.

Gå till Admin >> Git integration >> Konfigurerade integrationer >> Klicka på namnet
Klicka på i sidomenyn arkiv
Klicka på namnet på en
Klicka på Registrera alla integrationer

Detta kommer att manuellt tvinga fram skapandet av webhook i rätt form.

Om webhook finns, men innehåller felindikationer, kontrollera felmeddelandet och försök lösa därefter.

2 Refererar till nyckelord

Nu när den allmänna anslutningen är konfigurerad har du redan information från GitHub i Easy Redmine och du kan använda den. Men för att dra full nytta av integrationen finns det ytterligare ett par inställningar. Vissa är redan förinställda och du kan bara kontrollera dem.

Det är möjligt att koppla särskilda commits eller pull-förfrågningar till särskilda uppgifter, och till och med logga tid på detta sätt utan att behöva besöka Easy Redmine. Detta görs av sk hänvisar till nyckelord. När du använder dem i commit-meddelandet eller pull-begärans namn i kombination med uppgifts-ID, kommer det att skapa en länk mellan uppgiften och GitHub-objektet. De vanligaste exemplen är refs #1234 or stänger #1234

I de flesta fall hittar du några förinställda referenssökord. Så här arbetar du med dem.

Gå till global meny >> Git integration >> Referenser
Skapa eller redigera en referens
Hela formuläret innehåller verktygstips som hjälper dig att navigera dig igenom dem

De viktigaste reglerna att komma ihåg är:

Uppgiften måste identifieras i formulär #ID , t.ex. #1234
Loggningstid (om tillåtet) anges alltid som @XhYm , t.ex. @1h30m
Vid commits måste de refererande nyckelorden anges i begå meddelande
Vid pull-förfrågningar måste de refererande nyckelorden anges i namn av pull-begäran

3 Användarkartläggning

Eftersom vi har att göra med integration av två olika applikationer har de olika uppsättningar användare. Alla användarattribut på GitHub-relaterade enheter (författare till commit, granskare vid pull-begäran, etc.) i Easy Redmine + spenderad tid som loggas via referenser till nyckelord, bör kopplas till riktiga användare. Så hur mappas egentligen användare från GitHub till Easy Redmine?

Inget vetenskapligt här, användare mappas helt enkelt via e-post i båda användarprofilerna. Se till att dina utvecklare har identisk e-post i både GitHub och Easy Redmine.

Om, av någon anledning, en användare inte kan förena e-postmeddelanden i båda applikationerna, finns det möjlighet att ange ytterligare e-post i Easy Redmine i användarprofilen -> ange Github-e-postadressen här.

4 Hur det fungerar

Äntligen når vi den roliga delen. Vad integrationen faktiskt gör för användarna. Gå till huvudsidan/instrumentpanelen för Git-integrering via global meny (överst till höger) under avsnittet Tillägg.

Du hittar en anpassningsbar sida i standardläge, som du senare kan anpassa efter dina behov.

Den innehåller också en meny för att lista enheter eller ange inställningar. Som nämnts i introduktionen samlar och visar Easy Redmine fyra viktiga enheter från GitHub. Låt oss titta närmare på var och en av dem.

4.1 Förvar

Förvarslistan är funktionellt den minst intressanta, även om den verkligen är nödvändig. Ett användbart filter värt att nämna kallas Service, som du kommer att använda om du har olika GitHub-instanser anslutna och du behöver bara söka igenom några av dem.

Detalj av förvaret

Anmärkningar:

(Av-)Registrera alla integrationer beskrevs i kapitel 1.1. Det kommer att skapa/ta bort webhooks i GitHub-projektet.
Redigera - ändra vissa attribut manuellt. Det finns ingen annan anledning än avancerad felsökning att redigera några attribut för förvaret i Easy Redmine.
Synkronisera - laddar ner all aktuell data från förvaret.
Dra förfrågningar - listar alla pull-förfrågningar i detta arkiv.
Välj sekvensmall - fortfarande under utveckling, ge oss mer tid att polera detta robusta verktyg.

4.2 Pull-förfrågningar (kodförfrågningar)

Vi bör förtydliga varför det finns två namn. Dra begäran är termen som används i GitHub. Andra verktyg har andra namn på det, till exempel Sammanfogningsförfrågan. Integreringsmekanismen för vårt verktyg är skriven på ett generellt sätt, så att vi kan utöka stödet till andra Git-plattformar. Därför kan du hitta etikett i applikationen och bilderna Kodbegäran, vilket är en allmän term som kan tillämpas på Pull-förfrågningar eller Merge-förfrågningar.

Pull request är en rik enhet (lagrar alla viktiga attribut) som gör det möjligt att skapa fina listor, rapporter och till och med diagram ovanför dem direkt i Easy Redmine.

Detalj av pull-begäran

Anmärkningar:

Namnet på pull-begäran innehåller det refererande nyckelordet "refs" följt av uppgifts-ID med hash #765 - det är därför det länkades till uppgift 765
Genom att klicka på Synkronisera kommer att uppdatera all data om denna PR från GitHub
Alla attribut kan visas på listan över pull-förfrågningar
Alla attribut utom SHA kan användas som filter på pull-förfrågningars lista/rapport/diagram
Pull-förfrågningslistan innehåller också attribut för tester (CI/CD) relaterade till den, viktigast av allt - Teststatus

4.3 Åtar sig

I likhet med pull-förfrågningar ger listan över åtaganden också stora rapporteringsmöjligheter. Bekräftelselistan innehåller även attribut från tester.

Commit har ingen egen detaljvy i Easy Redmine. Det finns helt enkelt inget behov av det. Genom att klicka på URL (eller SHA) kommer du att dirigeras till dess detalj i GitHub.

4.4 tester

De nämndes i förhållande till enheterna ovan. Tester har också en egen lista för att generera olika rapporter. Förmodligen den vanligaste användningen kommer att vara livevisning av tester på de kritiska arkiven, såsom releasekandidater.

Testet har inte heller sin egen detaljvy, genom att klicka kommer du till GitHub.

4.5 Synergi - vy från uppgift

Låt oss ta en titt på hur allt går ihop.

1 Övergripande status för GitHub-enheter relaterade till denna uppgift. Den kan innehålla olika kombinationer av färger (röd, orange, grön) och ikoner (bocken, kryss). Det bästa är förstås grön bock i grön ram
Kombinationen beror på status för pull-begäran(er) och testresultat relaterade till commits och pull-begäranden. Syftet är att visa vid första anblicken hur den "tekniska" utvecklingen av denna uppgift går, särskilt användbart för QA- eller leveranschefer.

2 Namn på lagringsplatser som ändringarna som hänvisar till denna uppgift har genomförts i. Genom att klicka på länken kommer du att dirigeras till listan över dessa åtaganden.

3 Namn på pull-begäran som hänvisar till denna uppgift. Genom att klicka på den kommer du att dirigeras till detaljerna i PR i Easy Redmine.
Om det bara finns commits som hänvisar till denna uppgift men pull-begäran saknas, är detta värde tomt.

4 Status för varje pull-begäran. Genom att klicka på den kommer du att omdirigeras till detaljerna för pull-begäran i GitHub.
Om det bara finns commits som hänvisar till denna uppgift men pull-begäran saknas, är detta värde tomt.

5 Resultat av den senaste testkörningen i pull-begäran. Genom att klicka på den kommer du att dirigeras till GitHub. Det går inte att klicka in Okänd status (testet finns inte).
Om det bara finns commits som hänvisar till denna uppgift men pull-begäran saknas, visar värdet det senaste testresultatet som kördes på den senaste commiten.

6 Kör test manuellt - tar dig till GitHub.

7 Klicka för att skapa en pull-begäran. Användbart när du bara har en uppsättning commits, men saknar PR (tar dig till GitHub).

4.6 Skapa gren från uppgift

Vissa användare tycker att det är praktiskt att skapa en filial direkt från uppgiften.

Knappen finns i global meny på uppgiftsdetaljen

Välj arkivet i fältet för autoslutförande. Filialnamn är förifyllt med uppgifts-ID och ämne, men du kan ändra det. Källgren är förifylld av Master

Du kommer att se grenen som en tagg under Git integrationssektionen på uppgiften. Den är klickbar och leder till grenen i GitHub.

5 behörigheter

Det finns för närvarande två behörigheter.

Visa - Öppna tillägget från den globala menyn
Hantera - redigera instrumentpanelen

Den globala konfigurationen är endast tillgänglig för Easy Redmine admin.