# Een GitHub-repository koppelen Toon de codewijzigingen van een project bij de taken waar ze bij horen, zodat het hele team ziet wat er echt gebouwd is en wanneer. GitHub is de plek waar veel ontwikkelaars hun code bewaren. Elke wijziging die ze daar vastleggen heet een "commit", met een kort bericht erbij dat zegt wat er veranderd is. Koppel je een repository (de plek op GitHub waar de code van één project staat) aan een project in Taskstand, dan verschijnen die commits in Taskstand en hangen ze zichzelf aan de taak die ze noemen. Zo zie je bij een klantproject wat er echt gebouwd is, naast het werk dat erom vroeg. Komt er in je project geen code aan te pas? Dan valt er niets te koppelen en kun je deze pagina overslaan. ## Wat je nodig hebt | | | |---|---| | Abonnement | Het abonnement van de **eigenaar van het project** beslist. Elk betaald abonnement (Plus, Pro en Business) kan repositories koppelen, en de gratis proefperiode ook. Zie [abonnementen en limieten](). | | Wie koppelt | De eigenaar van het project, in de projectinstellingen. | | Wie ziet de commits | Eigenaar, Manager en Teamlid. | | Wie ziet ze nooit | Klant, Meelezer en Beperkt. | Een project kan meer dan één repository hebben, bijvoorbeeld een website naast een app, tot vijf. ## Een repository koppelen met de GitHub-app De makkelijkste manier is de app van Taskstand op GitHub. Je installeert hem één keer op je GitHub-account of organisatie en kiest welke repositories hij mag lezen. 1. Open het project, klik op **Projectinstellingen** (het tandwiel aan het eind van de projectbalk) en ga naar **Code**. 2. Klik onder **Code op GitHub** op **Installeer op GitHub**. 3. Kies op GitHub het account of de organisatie en welke repositories de app mag lezen. GitHub stuurt je daarna terug naar Taskstand. 4. Klik op **Kies een repository**, kies er een bij **Welke repository?** en klik op **Koppelen**. Staat de app al in je organisatie, omdat jij of een collega hem eerder installeerde? Klik dan op **Meld je aan met GitHub** in plaats van hem opnieuw te installeren. Mag je zelf geen apps installeren op een organisatie, dan vraagt GitHub dat aan de eigenaars van die organisatie. Zodra zij dat gedaan hebben, kom je terug en klik je op **Meld je aan met GitHub**. Staat de repository er niet tussen? Klik onder het formulier op **Kies op GitHub** om de app toegang te geven tot meer repositories of tot een andere organisatie. ### Wat de app mag De app vraagt GitHub om maar twee rechten: - **Contents: read**, om de commits te lezen. - **Metadata: read**, om de namen van de repositories en branches te zien. Hij schrijft nooit iets in je repository, verandert geen code en maakt geen issues of pull requests aan. Taskstand bewaart je code ook helemaal niet, zie verderop. ## Koppelen met een toegangstoken Kun je de app niet gebruiken, bijvoorbeeld omdat je organisatie dat niet toestaat, open dan op dezelfde pagina **Of koppel met een toegangstoken**. Een token is een soort wachtwoord dat alleen toegang geeft tot wat jij aanvinkt. 1. Maak op GitHub een fine-grained personal access token (de link **Maak een token** brengt je erheen). Beperk hem tot deze ene repository en geef hem deze rechten: - **Contents**: read - **Metadata**: read - **Webhooks**: read and write 2. Plak hem bij **GitHub access token** en klik op **Doorgaan**. Er is dan nog niets gekoppeld. 3. Kies de repository bij **Welke repository?** en klik op **Koppelen**. Met het webhookrecht vraagt Taskstand GitHub om elke nieuwe push (een nieuwe lading commits) meteen door te sturen. Zonder dat recht komt de geschiedenis wel binnen, maar nieuwe commits niet vanzelf, en dat staat dan ook in de instellingen. Een koppeling met een token kun je later overzetten naar de app met **Overzetten naar de GitHub-app** op de regel van de repository. De commits en de taken waar ze aan hangen blijven gewoon staan. ## Een taak noemen in een commitbericht Zet de verwijzing naar de taak in het commitbericht, en de commit verschijnt bij die taak: ``` Datumkiezer op het boekingsformulier hersteld (WEB-12) ``` De verwijzing is de sleutel van het project met het nummer van de taak erachter. Je ziet hem bovenaan elke taak, en met een klik erop kopieer je hem. Een link naar de taak plakken werkt ook. Eén commit mag meerdere taken noemen. Alleen `#12` werkt niet, omdat GitHub zulke nummers zelf in de merge-commits zet die het aanmaakt. Dan zou elke samengevoegde pull request bij de verkeerde taak terechtkomen. Alleen verwijzingen met de sleutel van dit project tellen, dus een commit die een taak uit een ander project noemt, laat dit project met rust. Verander je de sleutel van het project later, dan werken oudere verwijzingen niet meer. ## De geschiedenis en de branches Zodra je een repository koppelt, leest Taskstand de geschiedenis van elke branch (een aparte lijn van wijzigingen, zoals `main` of `dev`) terug tot het begin. De melding zegt **De commits zijn onderweg.** en de commits verschijnen zodra ze binnen zijn. Oudere commits die al een taak noemen, komen ook bij die taak te staan. Daarna komt elke push binnen enkele ogenblikken vanzelf binnen. Een commit staat vaak op meer dan één branch, bijvoorbeeld na een merge. Taskstand onthoudt welke branches bij elke commit komen, dus filter je op een branch, dan zie je alles wat erop staat. ## De Code-pagina Zodra er een repository gekoppeld is, krijgen Eigenaar, Manager en Teamlid een knop **Code** in de projectbalk. De lijst **Commits** daar toont elke commit, de nieuwste eerst, per dag gegroepeerd, met de taken die hij noemt. - **Zoek in het bericht of op een sha**: vindt een woord in het bericht, of een commit aan het begin van zijn sha (de code van de commit, zoals `3534da1`). - **Alle branches**: toon alleen de commits op één branch. - **Alle repositories**: toon één repository als het project er meerdere heeft. Gebruikt de auteur van een commit hetzelfde e-mailadres als een lid van het project, dan staat de foto van dat lid erbij. ## Een commit met de hand aan een taak hangen Vergeten de taak in het bericht te noemen? Dan hang je de commit alsnog aan de taak, vanuit de taak zelf: - **In een reactie**: noem de commit bij zijn sha, zoals `3534da1`, en hij hangt zichzelf aan de taak. - **Met de kiezer**: klik onder **Commits** op de taak op **Koppel een commit**, zoek in het bericht of plak een sha, en klik op de commit. **Verberg commits die al aan een andere taak hangen** laat de commits weg die al ergens anders werk doen. Een commit die Taskstand nog niet gelezen heeft, bijvoorbeeld van een branch waar sinds de koppeling niemand meer naar pushte, haal je op met **Haal … op bij GitHub** in de kiezer. Wil je een commit weer van een taak halen, beweeg er dan met de muis over en klik op **Koppel deze commit los**. ## De koppeling werkend houden Eén keer per dag vraagt Taskstand aan GitHub of elke koppeling nog werkt. Zegt GitHub duidelijk nee, dan wordt de koppeling uitgezet (je ziet **Uitgezet**) en staat er in de instellingen een rode regel met wat je moet doen. Een rode stip bij **Code** in de projectinstellingen laat zien dat er iets je aandacht vraagt. | Wat de instellingen zeggen | Wat je doet | |---|---| | GitHub weigert dit token | Vervang het token. | | Dit token mag geen webhook toevoegen | Vervang het token door een met **Webhooks: read and write**. | | De GitHub-app is verwijderd | Installeer de app opnieuw en koppel de repository. | | De GitHub-app is opgeschort | Hef de opschorting op GitHub op. | | De GitHub-app mag deze repository niet meer lezen | Voeg de repository op GitHub weer aan de app toe. | | Wie koppelde, kan er niet meer bij | Koppel opnieuw met een account dat er wel bij kan. | Een token heeft meestal een einddatum. De instellingen tonen **Token verloopt op …**, en die regel wordt een maand van tevoren oranje. Klik op **Vervang token** (het sleutelicoon) om een nieuw token te plakken: de commits blijven staan. Een koppeling via de app heeft geen token dat je hoeft te vervangen. **Lees deze repository opnieuw** (het icoon met de pijlen) leest de geschiedenis nog een keer als je denkt dat er iets ontbreekt. ## Loskoppelen of de app verwijderen - **Loskoppelen** (het kruisje op de regel) haalt de koppeling en **al haar commits** uit dit project. De taken zelf blijven staan. - **Ontkoppel** naast je GitHub-aanmelding zet elke repository uit die je daarmee koppelde, in al je projecten. De commits blijven staan. De app blijft op GitHub geïnstalleerd tot je hem daar verwijdert. - **De app op GitHub verwijderen** zet de koppelingen die erdoor lopen uit. De commits die al in Taskstand staan blijven, en koppel je de repository opnieuw, dan gaat hij verder waar hij gebleven was. Heeft de eigenaar een abonnement dat geen repositories meer bevat, dan blijven de koppeling en de commits staan, maar gaat de Code-pagina dicht. De eigenaar kan dan nog wel loskoppelen. ## Wat er bewaard wordt Van elke commit bewaart Taskstand: - de sha (de code van de commit) en de link ernaar op GitHub - het volledige bericht - de naam en het e-mailadres van de auteur, zoals git ze vastlegde - de datum - op welke branches hij staat, en welke taken hij noemt Je code zelf wordt nooit in Taskstand ingelezen of bewaard. Verwijder je het project of koppel je de repository los, dan verdwijnen de commits ook.