GitHub-integratie

0 Inleiding

GitHub Integration is een add-on die kan worden toegevoegd aan elk van de drie Easy Project-abonnementen.

Het doel van de plug-in is om belangrijke gegevens van GitHub in Easy Project te verzamelen om te helpen bij de rapportage, evaluatie en presentatie van ontwikkelingsactiviteiten, en zo de besluitvorming te ondersteunen van de kant van belanghebbenden die zijn geïnvesteerd in de softwareontwikkelingsprojecten en -processen van het bedrijf.

De mogelijkheden omvatten een zeer eenvoudige eerste verbinding met uw GitHub-instantie (zowel zelf-gehoste als cloudversies). Wanneer de verbinding tot stand is gebracht, toont Easy Project de meest cruciale items van GitHub in configureerbare en filterbare lijsten (vergelijkbaar met een takenlijst). Deze entiteiten zijn:

• Vindplaatsen
• Pull-verzoeken
• commits
• Tests

inclusief hun belangrijkste eigenschappen.

Een belangrijk element van de integratie is dat Easy Project de repositories NIET fysiek kopieert. De code blijft in GitHub.

1 Verbinding tot stand brengen

Ten eerste moet u een toegangstoken hebben van een gebruiker in GitHub, met de juiste machtigingen.

1. Selecteer een gebruiker via wie Easy Project toegang krijgt tot GitHub. Dit kan een speciale gebruiker zijn waar niemand zich aanmeldt, bijvoorbeeld er_integrator
   
2. Log in op GitHub door deze gebruiker
3. Klik op de avatar >> Instellingen
   
   
4. Instellingen voor ontwikkelaars
   
   
5. Persoonlijke toegangstokens
   
   
6. Genereer nieuwe token
   
   
7. U moet deze bereiken toestaan
   - repo (volledige controle over privérepository's)
   - admin:repo_hook (Volledige controle over repository hooks)
   - gebruiker (update ALLE gebruikersgegevens)
8. Kopieer de token
   
   Nu kunt u naar Easy Project gaan en de essentiële informatie invoeren
   
   
9. Ga naar Admin >> Git integratie >> Find Beschikbare integraties en druk op Toevoegen
   
   
10. Geef uw verbinding een naam, voer de URL in en het toegangstoken dat u eerder hebt gegenereerd.
    Opmerking: In geval van bewolking, bijv https://github.com/robogithub-easy , voer gewoon in https://github.com/ zonder de sub-url. U hoeft zich geen zorgen te maken, u kunt alleen projecten zien die de gebruiker met toegangstoken kan zien. Als u al uw projecten als privé instelt, kan niemand anders ze zien.
    
    
11. Bespaar
    
12. Dat is het! Verbinding is gemaakt.

Al het andere wordt automatisch op de achtergrond gedaan. Met name

• Easy Project haalt alle projecten/repositories op waarvan de gebruiker met toegangstoken lid is
  
• In deze repositories worden webhooks gemaakt => zodat informatie over nieuwe commits, pull-verzoeken en tests naar Easy Project wordt verzonden
  

1.1 Problemen met verbindingen oplossen

Probleem A
Ik zie geen repository van deze GitHub-instantie
Door onvoorziene omstandigheden kan het voorkomen dat bovengenoemde werkzaamheden niet succesvol worden uitgevoerd. Als gevolg hiervan ziet u mogelijk geen repository van deze GitHub-instantie in Easy Project.

In dat geval kunt u de repositories handmatig importeren, met slechts een paar klikken.

1. Ga naar Admin >> Git integratie >> Geconfigureerde integraties >> Klik op de naam
   
   
2. Klik in het zijmenu op Opslagplaats toevoegen
   
   
3. Vind de repository
   
   
4. Na het selecteren worden andere velden automatisch ingevuld
   
5. Klik Bespaar
   Opslagplaats is toegevoegd
   
   
   

Probleem B
Er zijn repositories gevonden, maar mijn nieuwe commits, pull-verzoeken en tests zijn niet toegevoegd aan Easy Project
Nieuwe gegevens van GitHub worden naar Easy Project verzonden via webhooks die in GitHub zijn geconfigureerd. Onder normale omstandigheden worden ze automatisch aangemaakt. U kunt dit verifiëren in uw GitHub-project >> Instellingen >> Webhooks

Als er geen webhook is met de link naar uw applicatie, moet u deze maken. Nogmaals, dit is een eenvoudige handeling.

1. Ga naar Admin >> Git integratie >> Geconfigureerde integraties >> Klik op de naam
   
   
2. Klik in het zijmenu op Vindplaatsen
   
   
3. Klik op de naam van een
   
   
4. Klik op Registreer alle integraties
   
   

Dit zal handmatig het aanmaken van de webhook in de juiste vorm forceren.

Als de webhook bestaat, maar een foutmelding bevat, controleer dan de foutmelding en probeer dienovereenkomstig op te lossen.

2 Verwijzende trefwoorden

Nu de algemene verbinding is geconfigureerd, heb je al informatie van GitHub in Easy Project en kun je deze gebruiken. Om echter volledig te profiteren van de integratie, zijn er nog een paar instellingen. Sommige zijn al vooraf ingesteld en u kunt ze alleen controleren.

Het is mogelijk om bepaalde commits of pull-verzoeken aan bepaalde taken te koppelen, en zelfs tijd te loggen op deze manier zonder dat je Easy Project hoeft te bezoeken. Dit wordt gedaan door zogenaamde verwijzende trefwoorden. Wanneer je ze gebruikt in het commit-bericht of de naam van het pull-verzoek in combinatie met de taak-ID, wordt er een koppeling gemaakt tussen de taak en het GitHub-item. De meest voorkomende voorbeelden zijn: referenties #1234 or sluit #1234

In de meeste gevallen vindt u enkele vooraf ingestelde referentiesleutelwoorden. Hier leest u hoe u met hen kunt werken.

1. Ga naar algemeen menu >> Git-integratie >> Referenties
2. Een referentie maken of bewerken
3. Het hele formulier bevat tooltips om u te helpen er doorheen te navigeren
   
   

De belangrijkste regels om te onthouden zijn:

• Taak moet worden geïdentificeerd in de vorm #ID, bijv. #1234
• Logtijd (indien toegestaan) wordt altijd ingevoerd als @XhYm , bijv. @1h30m
  
• Bij commits moeten de refererende trefwoorden worden ingevoerd in de commit bericht
• Bij pull-verzoeken moeten de referentiesleutelwoorden worden ingevoerd in de naam van het pull-verzoek

3 gebruikerstoewijzing

Omdat we te maken hebben met de integratie van twee verschillende applicaties, hebben ze elk verschillende sets gebruikers. Alle gebruikersattributen op GitHub-gerelateerde entiteiten (auteur van commit, recensent op pull-verzoek, enz.) in Easy Project + doorgebrachte tijd die is vastgelegd via referentiesleutelwoorden, moeten worden verbonden met echte gebruikers. Dus, hoe worden gebruikers van GitHub eigenlijk toegewezen aan Easy Project?

Niets wetenschappelijks hier, gebruikers worden eenvoudig in kaart gebracht via de e-mail in beide gebruikersprofielen. Zorg ervoor dat uw ontwikkelaars identieke e-mails hebben in zowel GitHub als Easy Project.

Als, om welke reden dan ook, één gebruiker de e-mails in beide applicaties niet kan verenigen, is er de mogelijkheid om extra e-mail in Easy Project in te voeren in het gebruikersprofiel -> voer hier het Github-e-mailadres in.

4 Hoe het werkt

Eindelijk komen we bij het leuke gedeelte. Wat de integratie daadwerkelijk doet voor de gebruikers. Ga naar de hoofdpagina/dashboard van Git-integratie via het globale menu (rechtsboven) onder de sectie Add-ons.

U vindt een aanpasbare pagina in een standaardstatus, die u later op uw behoeften kunt afstemmen.

Het bevat ook een menu om entiteiten weer te geven of instellingen in te voeren. Zoals vermeld in de inleiding, verzamelt en toont Easy Project 4 cruciale entiteiten van GitHub. Laten we elk van hen nader bekijken.

4.1 Opslagplaatsen

De lijst met repositories is functioneel het minst interessant, hoewel echt noodzakelijk. Een handig filter dat het vermelden waard is, wordt genoemd Service, die u zult gebruiken als u verschillende GitHub-instanties hebt aangesloten en u slechts enkele ervan hoeft te doorzoeken.

Detail van opslagplaats

Opmerkingen:

• (De-)Registreer alle integraties werden beschreven in hoofdstuk 1.1. Het zal webhooks maken/verwijderen in het GitHub-project.
• Edit - wijzig enkele attributen handmatig. Er is geen andere reden dan geavanceerde foutopsporing om attributen van de repository in Easy Project te bewerken.
  
• Synchroniseren - downloadt alle actuele gegevens uit de repository.
• Pull-verzoeken - geeft een overzicht van alle pull-verzoeken in deze repository.
• Volgordesjabloon kiezen - nog in ontwikkeling, geef ons alstublieft meer tijd om deze robuuste tool op te poetsen.

4.2 Pull-verzoeken (Code-verzoeken)

We moeten verduidelijken waarom er twee namen zijn. Pull-verzoek is de term die wordt gebruikt in GitHub. Andere tools hebben er bijvoorbeeld andere namen voor: Verzoek samenvoegen. Het integratiemechanisme van onze tool is op een algemene manier geschreven, zodat we de ondersteuning naar andere Git-platforms kunnen uitbreiden. Daarom kunt u in de toepassing en afbeeldingen label vinden Code aanvraag, wat een algemene term is die kan worden toegepast op Pull-verzoeken of Merge-verzoeken.

Pull-verzoek is een rijke entiteit (slaat alle belangrijke attributen op) waarmee u direct in Easy Project mooie lijsten, rapporten en zelfs grafieken erboven kunt maken.

Detail van pull-verzoek:

Opmerkingen:

• De naam van het pull-verzoek bevat het referentiesleutelwoord "refs" gevolgd door de taak-ID met hash #765 - daarom was het gekoppeld aan taak 765
• Door te klikken op Synchroniseren zal alle gegevens van deze PR bijwerken vanuit GitHub
• Alle attributen kunnen worden weergegeven op de lijst met pull-verzoeken
• Alle attributen behalve SHA kunnen worden gebruikt als filters op de lijst/rapport/grafiek van pull-verzoeken
• De lijst met pull-verzoeken bevat ook attributen van tests (CI/CD) die ermee verband houden, vooral - Teststatus

4.3 Toezeggingen

Net als bij pull-verzoeken, biedt de lijst met commits ook uitgebreide rapportagemogelijkheden. De commit-lijst bevat ook attributen uit tests.

Commit heeft geen eigen detailweergave in Easy Project. Er is gewoon geen behoefte aan. Door op URL (of SHA) te klikken, wordt u naar de details in GitHub geleid.

4.4-tests

Ze werden genoemd met betrekking tot de bovengenoemde entiteiten. Tests hebben ook hun eigen lijst om verschillende rapporten te genereren. Waarschijnlijk zal het meest gebruikte gebruik de liveweergave zijn van tests op de kritieke repositories, zoals release-kandidaten.

Test hebben ook geen eigen detailweergave, klikken brengt u naar GitHub.

4.5 Synergie - weergave vanuit taak

Laten we eens kijken hoe het allemaal in elkaar zit.

1 Algemene status van GitHub-entiteiten met betrekking tot deze taak. Het kan verschillende combinaties van kleuren (rood, oranje, groen) en pictogrammen (vinkje, kruisje) bevatten. De beste is natuurlijk een groen vinkje in een groen kader
De combinatie is afhankelijk van de status van pull-verzoek(en) en testresultaten met betrekking tot commits en pull-verzoeken. Het doel is om op het eerste gezicht te laten zien hoe de "technische" voortgang van deze taak verloopt, vooral handig voor QA- of leveringsmanagers.

2 Naam van de repository('s) waarin de wijzigingen met betrekking tot deze taak zijn vastgelegd. Door op de link te klikken wordt u doorverwezen naar de lijst met deze commits.

3 Naam van pull-verzoek(en) die naar deze taak verwijzen. Door erop te klikken wordt u doorverwezen naar het detail van de PR in Easy Project.
Als er alleen commits zijn die naar deze taak verwijzen, maar een pull-verzoek ontbreekt, is deze waarde leeg.

4 Status van elk pull-verzoek. Door erop te klikken, wordt u doorgestuurd naar het detail van het pull-verzoek in GitHub.
Als er alleen commits zijn die naar deze taak verwijzen, maar een pull-verzoek ontbreekt, is deze waarde leeg.

5 Resultaat van de laatste testrun in het pull-verzoek. Door erop te klikken wordt u doorverwezen naar GitHub. Het is niet aanklikbaar in Onbekend status (test bestaat niet).
Als er alleen commits zijn die naar deze taak verwijzen, maar een pull-verzoek ontbreekt, toont de waarde het laatste testresultaat dat is uitgevoerd op de laatste commit.

6 Test handmatig uitvoeren - brengt u naar GitHub.

7 Klik om een ​​pull-aanvraag te maken. Handig als je alleen een set commits hebt, maar de PR mist (brengt je naar GitHub).

4.6 Vertakking maken van taak

Sommige gebruikers vinden het handig om direct vanuit de taak een branch aan te maken.

De knop is te vinden in de globaal menu op het taakdetail

Kies de repository in het veld voor automatisch aanvullen. Taknaam is vooraf ingevuld met taak-ID en onderwerp, maar u kunt dit wijzigen. Brontak is vooraf ingevuld door meester

Je zult de branch zien als een tag onder de Git-integratiesectie van de taak. Het is klikbaar en leidt naar de branch in GitHub.

5 machtigingen

Er zijn momenteel twee machtigingen.

• Bekijken - Toegang tot de add-on vanuit het globale menu
  
• Beheer - bewerk het dashboard
  

De globale configuratie is alleen toegankelijk voor Easy Project admin.