Hoe u GitHub Continuous Integration-pipelines instelt met self-hosted runners op Ubuntu 22.04.

Inleiding

Software Engineering is een snel en competitief vakgebied. Het sneller uitrollen van uw producten naar gebruikers geeft u een voorsprong op uw concurrenten. Gelukkig zijn er best practices in de sector om bedrijven een gelijk speelveld te bieden.

Continuous Integration and Continuous Development (CICD) is een voorbeeld van een strategie die gebruikmaakt van best practices in de sector om bedrijven een voorsprong te geven in dit competitieve veld.

GitHub, een webgebaseerde repository met Git, een tool voor versiebeheer, stelt softwareontwikkelaars, engineers en architecten in staat om CI/CD te implementeren. Continuous Development (CD) is de praktijk van het automatiseren van builds, tests en implementaties. Continuous Integration (CI) stelt veel mensen in staat om aan hetzelfde project samen te werken en te controleren of de code werkt zonder zich zorgen te hoeven maken over merge-conflicten.

Met GitHub Actions kunnen we stappen schrijven die builds, tests en implementaties automatiseren.

In deze handleiding leert u hoe u Continuous Integration instelt met GitHub Actions. We beginnen met het opzetten van een Git-repository om onze code te hosten. Vervolgens configureren we een GitHub CI-proces om wijzigingen in onze code te controleren, een CI-runner te starten om tests uit te voeren, en onze applicatie te bouwen en te implementeren op een Ubuntu 22.04-server die Nginx draait.

Vereisten

Om deze handleiding te volgen, heeft u het volgende nodig:

• Een server met Ubuntu 22.04. U kunt deze handleiding volgen voor de initiële Ubuntu-serverinstallatie, een non-root gebruiker toevoegen, en de UFW-firewall van Ubuntu inschakelen.

• U moet Node.js op uw server hebben geïnstalleerd, bij voorkeur versie 14 of hoger. We hebben een handleiding over hoe u Node.js installeert op Ubuntu.

• U moet Nginx-serversoftware hebben geïnstalleerd. We hebben een handleiding over Hoe u Nginx installeert op een server met Ubuntu.

• U heeft Docker en Docker Compose nodig op uw lokale machine om een geïsoleerde ontwikkelomgeving uit te voeren. Volg onze handleiding om te leren Hoe u Docker installeert en bedient in de cloud.

Nu we alles hebben wat we nodig hebben, laten we beginnen.

Stap 1. De projectrepository klonen.

We gaan deze handleiding baseren op Reactjs, een declaratieve JavaScript-bibliotheek voor het bouwen van gebruikersinterfaces. Als u vanaf nul een nieuw project wilt opzetten, kunt u deze bron over het opzetten van een React-app gebruiken. Kortheidshalve gebruiken we een kloon van deze React.js-repo die we al hebben opgezet op GitHub.

De applicatie die we klonen is een eenvoudige React-applicatie met react-router 6 en een test uitgevoerd met React Testing Library, wat ons methoden geeft om toegang te krijgen tot de DOM.

Om de repository te klonen, klikt u op de groene knop en kopieert u de URL.

Open de terminal in uw werkruimte en voer de onderstaande opdracht uit om de app te klonen:

Zodra u de repository heeft gekloond, navigeert u naar de projectmap:

Voer de opdracht docker-compose up uit om de app te bouwen en uit te voeren:

Wanneer het proces is voltooid, gaat u naar http://localhost:3000

U zou iets vergelijkbaars met dit moeten zien:

Stap 2. Het Node.js.yml-bestand begrijpen.

In deze stap definiëren we de richtlijnen in het GitHub Yaml-bestand om ons te helpen begrijpen wat er gebeurt. In de repository bevindt zich een map .github/workflows die een node.js.yml bestand bevat, dat workflowstappen heeft die GitHub-runners volgen nadat u wijzigingen naar uw coderepository op GitHub pusht. YAML-syntaxis wordt gebruikt om workflows voor GitHub Actions te schrijven. YAML-bestanden eindigen met een extensie yaml of yml.

Open het node.js.yml bestand, het zou er zo uit moeten zien:

Ten tijde van het schrijven van deze handleiding gebruikten we versie 16 van Node.js 16. Laten we nu de GitHub Actions-workflow begrijpen:

• name

name: cicd-tut

De naam van je workflow, deze naam zal worden getoond in je repository Actions tab.

• on

on wordt gebruikt om gebeurtenissen te definiëren. Gebeurtenissen kunnen automatisch een workflow activeren of voor later worden gepland. Gebeurtenissen kunnen enkelvoudig of meervoudig zijn, en je kunt ook workflow-uitvoeringen specificeren voor specifieke branches, tags of bestanden. Dit werkt als een filter.

In ons YAML-bestand definiëren we meerdere automatische gebeurtenissen, dit zijn:

• Een push gebeurtenis wordt geactiveerd wanneer code wordt gecommit naar een repository

• Een pull_request gebeurtenis wordt geactiveerd wanneer een pull request wordt aangemaakt op de main branch.

We specificeren een branch-naam main om de uitvoering van de workflow te beperken tot alleen die branch. We kunnen ook branches specificeren die moeten worden genegeerd met behulp van de !-vlag gevolgd door de branchnaam.

• jobs

Een workflow bestaat in wezen uit een of meerdere jobs. Deze jobs worden achtereenvolgens uitgevoerd van de eerste tot de laatste.

Elke job wordt uitgevoerd in een runner-omgeving die wordt gespecificeerd door runs-on. Je kunt ervoor kiezen om jobs uit te voeren op GitHub-runners, aangeduid met ubuntu-latest of een self-hosted runner aangeduid met self-hosted. Je keuze is afhankelijk van het aantal jobs dat je nodig hebt. Met self-hosted runners heb je meer flexibiliteit en controle over resources.

In onze volgende stap zullen we onze jobs eerst op GitHub-runners uitvoeren, en later zullen we een GitHub self-hosted runner op onze eigen server instellen.

• strategy

Met strategy kunnen we variabelen gebruiken in een enkele jobdefinitie om automatisch meerdere job-runs te maken die zijn gebaseerd op de combinaties van variabelen.

In ons YAML-bestand hebben we één variabele voor onze node-versie, maar als we er nog een toevoegen voor node-versie 18, zoals dit: node-version: [16.x, 18.x], dan zal de matrix-strategie 2 job-runs maken voor onze react-applicatie voor zowel node-versie 16 als 18.

• steps

Stappen zijn een reeks taken die een job vormen. Stappen kunnen commando's uitvoeren, taken instellen, acties in je openbare repository uitvoeren, of acties die zijn gepubliceerd in een docker-registry.

Een stap heeft een naam. Hoewel dit optioneel is, kun je het gebruiken om een eenvoudige manier op te geven om de naam van je stap te identificeren die op GitHub wordt weergegeven.

In een stap kun je een actie selecteren om in je job uit te voeren; acties zijn herbruikbaar. Versies van een actie worden gespecificeerd bij het definiëren van een actie. Dit is belangrijk omdat het voorkomt dat je workflow kapotgaat wanneer de eigenaar van de actie een update publiceert.

In het bovenstaande codefragment, checkout@v3 is een voorbeeld van een actie met een gespecificeerde versie 3. Deze actie checkt je repository uit zodat je workflow er toegang toe heeft.

Sommige acties zoals de actions/setup-node@v3 hierboven hebben invoerwaarden die worden aangeduid met het with trefwoord, de setup node-acties vereisen node versie 16 en dat npm gecached wordt.

• run

Deze actie voert opdrachtregelprogramma’s uit met behulp van de shell van het besturingssysteem.

In het bovenstaande YAML-bestand hebben we drie commando's, die beide worden uitgevoerd met dezelfde shell in de runner-omgeving.

• Het eerste commando npm i installeert alle afhankelijkheden die nodig zijn voor onze react-applicatie.

• Het tweede npm test, voert de test uit die we hebben geschreven. De test verwacht dat de tekst learn react wordt gerenderd op de Home-pagina.

• Ten slotte, npm run build-commando maakt een build-map met een productie-build van onze applicatie. Later gaan we deze build-map gebruiken in ons Nginx-serverblok.

Stap 3. GitHub CI testen met GitHub Runners.

In deze stap testen we het Continuous Integration-proces met GitHub-runners. Begin met het openen van het node.js.yml-bestand. Wijzig het type runner waarop de acties worden uitgevoerd naar ubuntu-latest. Het doel hiervan is om te testen of de GitHub-workflow perfect werkt op GitHub-runners voordat we onze eigen self-hosted runners opzetten.

Maak een nieuwe repository aan op je GitHub-account. Voordat we doorgaan, ga je terug naar je werkruimtemap en verwijder je de .git-map, als je deze niet kunt zien, controleer dan je verborgen bestanden. Je kunt het volgende commando in je terminal gebruiken om de map te verwijderen:

Nu kun je met git al je projectbestanden toevoegen, committen en pushen naar je repository. Als je vastloopt, gebruik dan deze handleiding over het verbinden van je projectmap met de GitHub-repository die je hierboven hebt gemaakt.

Wanneer je klaar bent, klik dan op het tabblad Code in je repo, en je ziet een kleine oranje stip naast het totale aantal commits. Als je erop klikt, zie je een modaal venster vergelijkbaar met dat hieronder, wat aangeeft dat je workflow in de wachtrij is geplaatst:

Klik nu op de Details-link in het modale venster of ga naar het tabblad Actions, je ziet elke stap van de node.js.yml-workflow die wordt uitgevoerd door GitHub-runners:

Als dit is gelukt, klik dan op het tabblad Actions, het zou er zo uit moeten zien:

En dat is het, de kleine oranje stip op ons Code-tabblad zou nu een groen vinkje moeten zijn. GitHub-runner heeft onze applicatie met succes gebouwd.

Laten we nu een stap verder gaan en de build-omgeving wijzigen om GitHub self-hosted runners te gebruiken in onze eigen Ubuntu-serverinfrastructuur.

Stap 4. GitHub-workflow instellen om een self-hosted runner te gebruiken.

Voordat we de self-hosted runner op onze server installeren, gaan we terug naar onze werkruimte en bewerken we het node.js.yml  workflowbestand om uit te voeren op GitHub self-hosted runners.

In dit stadium, wanneer je de wijzigingen commit, wordt de job in de wachtrij geplaatst omdat er nog geen self-hosted runner is gedefinieerd.

Klik in je repository op het tabblad Settings, klik in de linkerzijbalk op Actions, en klik vervolgens op Runners:

Klik op New self-hosted runner, en selecteer Linux als het besturingssysteem.

Je ziet instructies die je laten zien hoe je de runner kunt downloaden en op je server kunt installeren.

Stap 5. Een GitHub self-hosted runner installeren en configureren op onze server.

In deze stap gaan we een self-hosted GitHub runner instellen. Een self-hosted runner is een systeem dat de uitvoering van taken van GitHub Actions op de GitHub-website kan implementeren en beheren. Een voordeel van de self-hosted runner ten opzichte van de door GitHub gehoste runner is flexibiliteit. Het biedt meer controle over het besturingssysteem, de hardware en andere tools die kunnen worden aangepast aan de behoeften van uw gewenste applicatie.

Self-hosted runners kunnen op verschillende niveaus worden toegevoegd, zoals:

• Runners op repository-niveau, deze zijn specifiek voor een enkele repository.

• Runners op organisatie-niveau, deze kunnen taken verwerken voor meerdere repositories in een organisatie.

• Enterprise-niveau, die kunnen worden toegewezen aan meerdere organisaties.

Log in op uw server via ssh om door te gaan:

Ga naar uw thuismap met het commando:

Maak vervolgens een map aan genaamd action-runners en navigeer er naartoe:

Download vervolgens de nieuwste versie van het runner-pakket:

Pak vervolgens het gedownloade pakket uit met het commando:

Terug naar uw repository, klik op het tabblad Settings in het linkerpaneel op Actions, en dan Runners, net zoals we deden in Step 4.

U ziet een commando staan met een token dat uw self-hosted runner koppelt aan uw GitHub-repository. Terwijl u zich nog in de map bevindt waarin u de GitHub runner-code hebt uitgepakt, gebruikt u het vermelde commando om uw runner te koppelen, bijvoorbeeld:

Het zou succesvol moeten authenticeren:

Druk op enter voor de Default runner-groep.

Voer vervolgens een naam in voor uw runner, bijvoorbeeld my-runner, en druk op enter.

Druk op Enter om het toevoegen van extra labels over te slaan. U zou het succesbericht in de onderstaande schermafbeelding moeten zien:

Voer de naam van uw werkmap in, bijvoorbeeld react-cicd, dit zou succesvol moeten zijn met de tekst settings saved.

Start ten slotte ./run.sh, dit zou het volgende moeten tonen: Connected to Github:

Maar dit draait niet op de achtergrond. Als we ctrl+c typen in onze terminal, wordt de runner gestopt. We moeten deze vervangen door de .svc.sh service om de runner actief te houden als een service, zodat we ermee kunnen blijven communiceren.

Stop de runner met ctrl+c. U kunt de .svc.sh-service installeren door het volgende commando uit te voeren:

Zodra het is geïnstalleerd, start u de service met het commando:

Dit zou succesvol moeten zijn en het volgende tonen: active (running).

Om te bevestigen dat de svc.sh service actief is en draait, voert u het volgende commando uit:

Op dit punt zou elke workflow die in de wachtrij stond te wachten op een self-hosted runner succesvol moeten worden uitgevoerd. U kunt ook een bestand bewerken en dingen uitproberen. Wijzig bijvoorbeeld het Over.tsx-bestand, commit en push de wijzigingen, en de self-hosted runner zal de taak succesvol voltooien.

Stap 6. Nginx-serverblok instellen

In deze stap richten we een serverblok in Nginx in om de build-versie van onze React-applicatie te bekijken. We hebben een handleiding over Het instellen van Nginx-serverblokken die u wellicht nuttig vindt.

Hieronder vindt u een voorbeeld van een server blok dat in deze handleiding wordt gebruikt:

Je gaat een Nginx server block configuratiebestand aanmaken in de /etc/nginx/sites-available map.

Open een bestand voor de server block configuratie van je site met de nano-editor met behulp van het commando:

Kopieer het hierboven gedeelde server block, pas het aan op basis van je mappaden en plak het in het geopende bestand. Wanneer je klaar bent met bewerken, druk op ctrl+x druk vervolgens op y en enter om op te slaan en af te sluiten.

Maak na het opslaan een symlink voor de react-cicd server block configuratie van /etc/nginx/sites-available naar /etc/nginx/sites-enabled door het volgende commando uit te voeren:

Om de wijzigingen door te voeren, moet je Nginx herstarten. Voordat je de Nginx-service herstart, moet je echter controleren of de Nginx-configuraties geldig zijn door het volgende commando uit te voeren:

Als de configuratie correct is, zou de test succesvol moeten zijn.

Let op de waarde van de server_name richtlijn “ react.test ” in het server block? Je voegt deze waarde toe aan je hosts bestand op je lokale machine. Hiermee kun je de applicatie in je browser openen. Deze stap is alleen nodig voor virtuele domeinen die in lokale ontwikkelomgevingen worden gebruikt. Als je een geregistreerde domeinnaam hebt die is gekoppeld aan een openbaar IP-adres van je server, dan zou de domeinnaam al toegankelijk moeten zijn in je browser.

Open op je lokale machine het hosts-bestand met het commando:

Voeg in het hosts-bestand het IP-adres van je server toe, bijv. 127.0.0.1, gevolgd door je virtuele domeinnaam.

Hieronder zie je een voorbeeld. Sluit vervolgens het bestand en sla het op:

Terug op je server in de /var/www map, maak een nieuwe map aan, je kunt deze react-cicd noemen door het volgende uit te voeren:

In dit stadium zullen we het laatste commando in het node.js.yml bestand uit commentaar halen.

Dit commando kopieert de build-map van onze react-applicatie van de plaats waar we onze werkmap hebben opgegeven in de actions-runner-map in de vorige step 5.

En plaatst de public map in de /var/www/react-cicd map.

Het server block heeft nu toegang tot onze app en kan deze in een browser weergeven.

Herstart ten slotte de Nginx-service met het commando:

Nu kun je een wijziging aanbrengen in het Over.tsx bestand, en vervolgens je wijzigingen committen en pushen naar je repository. Na een succesvolle build zie je de build-versie van je react-app op http://react.test of op de domeinnaam die je hebt opgegeven. Vermijd het bewerken van het href element in het Home.tsx bestand, omdat dit ertoe kan leiden dat de reeds geschreven test mislukt. Het Actions tabblad in je repository zou ook de voltooide job build moeten tonen.

Conclusie

Continue integratie met Github Actions biedt veel voordelen, waaronder een goede ontwikkelaarservaring, het helpt bij continu testen, maakt eenvoudigere samenwerking in grotere teams mogelijk, verkort de ontwikkeltijd, zorgt voor snelle releases van nieuwe functies, realtime feedback en klanttevredenheid, waardoor u een voorsprong heeft op uw concurrenten. Om op deze kennis voort te bouwen, wilt u misschien ook meer leren over Het opzetten van GitLab Continuous Integration (CI) Pipelines op Ubuntu. en het gebruik van een Zelfbeheerde GitLab-instantie om uw Docker Images te hosten en privébuilds uit te voeren.

Veel computerplezier!