GitHub-repon forkkaaminen

GitHub-reposta voi tehdä ns. forkkauksen, joka tekee koko projektista sellaisen kopion, johon voi vapaasti tehdä muutoksia ilman, että alkuperäiseen projektiin tulee muutoksia. Seuraavaksi teemme GitHubista löytyvästä pienimuotosesta PHP-projektista forkkauksen, johon teemme jatkossa omia muutoksia.

1. Kirjaudu omilla tunnuksillasi GitHub-palveluun.

2. Mene osoitteeseen https://github.com/pekkatapio/perhekalenteri.

3. Klikkaa oikeassa yläkulmassa olevaa Fork-nappia.

   
   
   

   Tämä luo projektista kopion oman GitHub-tunnuksen alle. Tämä ilmenee sivun vasemmassa yläreunassa, josta näkyy repon sijainti omalla tunnuksella sekä mistä reposta se on alunperin kopioitu.

   
   
   

SSH-avaimien luonti ja lisääminen

Jotta kloonatun GitHub-repon käsittely paikallisesti olisi jouhevaa, kannattaa luoda sitä varten omat SSH-avaimet, jotka liitetään osaksi GitHub-tunnusta.

SSH-avaimien luominen

1. Avaa SSH-yhteys neutroni-palvelimelle omilla tunnuksillasi. Tämä onnistuu esimerkiksi käyttämälläsi pääteohjelmalla tai vaikka komennolla ssh tunnus@neutroni.hayo.fi.

2. Luo uusi SSH-avain komennolla

   ssh-keygen -t ed25519 -f ~/.ssh/github
   

   Tämä kysyy sinulta kahteen kertaan avaimelle tallennettavan salasanan. Käytön helpottamiseksi salasanan voi jättää tyhjäksi eli voit painaa Enter-näppäintä kummankin kysymyksen kohdalla. Tämän jälkeen ruudulle tulostuu seuraavankaltainen tieto, joka kertoo minne julkinen avain (github.pub) ja yksityinen avain (github) on tallennettu sekä siihen liittyvän "sormenjäljen".

   Generating public/private ed25519 key pair.
   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in /home/koodaaja/.ssh/github.
   Your public key has been saved in /home/koodaaja/.ssh/github.pub.
   The key fingerprint is:
   SHA256:d9vgxKdE1C+MvStN7CM2vDylek5XkUBoBVShVY0gpT8 koodaaja@neutroni
   The key's randomart image is:
   +--[ED25519 256]--+
   |          o+XXoo.|
   |           *o + o|
   |          o..+ + |
   |           +. + o|
   |        S . E..o.|
   |         . = B=. |
   |           .=*o. |
   |           oX.=  |
   |          .=+* . |
   +----[SHA256]-----+
   

SSH-avaimen lisääminen GitHub-palveluun

Seuraavaksi liitetään SSH-avain osaksi GitHub-tunnusta. Huomaa, että seuraavat vaiheet antavat käyttöoikeuden GitHub-palveluun ainoastaan neutroni-palvelimen käyttäjälle. Jos haluat esimerkiksi oman paikallisen työasemasi käyttäytyvän samalla tavalla, niin sinun täytyy luoda vastaavanlaiset SSH-avaimen myös sille.

1. Tarvitset edellä luomasi SSH-avainparin julkista avainta, jonka liitämme osaksi omaa GitHub-tunnustamme. Saat julkisen avaimen näkyville komennolla

   cat ~/.ssh/github.pub
   

   Komennon tulostama sisältö on seuraavanlainen. Kopioi komennon tulostama rivi leikepöydälle, älä kopioi alla olevaa esimerkkiä, se ei toimi.

   ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBaNMTbtiW9ybUK52raIDHKjQKglVqD6mbdPtPbMhmqy koodaaja@neutroni
   

2. Klikkaa GitHub-palvelussa oikeassa yläkulmassa olevaa profiilikuvaketta ja valitse avautuvasta valikosta Settings-vaihtoehto.

   
   
   

   Valitse oikean reunan valikosta kohta SSH and GPG keys.

   
   
   

   Klikkaa SSH keys -kohdassa New SSH key-nappia.

   
   
   

   Kirjoita Title-kenttään teksti tunnus@neutroni, liitä Key-kenttään leikepöydälle kopioimasi julkinen avain ja paina lopuksi Add SSH key-nappia.

   
   
   

   Tämän jälkeen sinulla on SSH-avain tallennettu GitHub-tunnukseesi. Pystyt poistamaan sen SSH and GPG keys -sivulta, kun et sitä enää käytä.

   
   
   

SSH-avaimen sijainti

Oletuksena SSH-ohjelma etsii tietyn nimisiä avaimia .ssh-kansion alta. Edellä nimesimme SSH-avaimen tästä poikkeavasti, joten SSH-ohjelmalle tulee vielä kertoa, mistä se löytää SSH-avaimen yhteyden muodostamisen yhteydessä. Anna seuraava komento neutronin komentorivillä.

tee -a ~/.ssh/config << END
Host github.com
  HostName github.com
  IdentityFile ~/.ssh/github
END

SSH-yhteyden testaaminen

Lopuksi kannataa vielä testata, että SSH-yhteys onnistuu juuri lisäämälläsi SSH-avaimella. Tämä tapahtuu komennolla

ssh -T git@github.com

Tämä testaa, onnistuuko SSH-yhteyden muodostus GitHub-palvelimelle. Jos kaikki toimii, tulostuu sinulle seuraavanlainen teksti.

Hi fronttikoodaaja! You've successfully authenticated, but GitHub does not provide shell access.

Huomaa, että tässä materiaalissa näkyvät tunnisteet on vaihdettu, ne eivät toimi.

GitHub-projektin kloonaus

Seuraavaksi kloonaamme GitHub-repon paikallisesti neutroni-palvelimelle. Teemme repokopion perhekalenteri-dev -nimiseen kansioon, siihen kansioon tulemme jatkossa tekemään kaikki muutokset ja sieltä myös viemään tekemämme muutokset oman tunnuksen alla olevaan GitHub-repoon.

1. Haetaan ensin GitHub-projektin SSH-osoite. Mene GitHubissa aikaisemmassa vaiheessa forkkaamaasi perhekalenteri-projektin sivulle. Klikkaa sivulla olevaa vihreää Code-nappia, valitse avautuvasta ikkunasta SSH-vaihtoehto aktiiviseksi ja kopioi laatikossa oleva osoite leikepöydälle.

   
   
   

2. Anna seuraava komento neutronin komentorivillä. Korvaa komennossa [SSH-osoite]-teksti SSH-osoitteella, jonka kopioit edellisessä vaiheessa leikepöydälle.

   git clone [SSH-osoite] ~/public_html/perhekalenteri-dev
   

   Esimerkkikäyttäjällä tuo komento ja sen tulos olisi seuraavanlainen.

   
   
   

   Tämän jälkeen sinulla on projektista kopio neutroni-palvelimella. Voit käydä tutustumassa siihen osoitteessa https://neutroni.hayo.fi/~tunnus/perhekalenteri-dev.

   
   
   

Projektin julkaiseminen

Deployer-skriptin määrittely

Jatkossa tulemme hyödyntämään Deployer-skriptiä sovelluksen julkaisemisessa. Se on PHP-kielellä toteutettu työkalu, joka helpottaa PHP-kielellä toteutettujen sovellusten julkaisua. Se mahdollistaa mm. automaattisen palvelimen määrittelyn, katkeamattoman julkaisun, paluun takaisin edelliseen toimivaan versioon. Lisäksi sille on valmiita reseptejä useimpien kehyskirjastojen ja sovellusten julkaisemiseen.

Deployerin asennus on hyvin suoraviivaista: skriptin lataus, siirto bin-kansioon ja suoritusoikeuksien antaminen. Tämä asennus on tehty jo valmiiksi neutronilla, joten Deployerin käytön voi aloittaa saman tien.

Seuraavalla komennolla voit varmistaa, mikä versio Deployerista on asennettu.

koodaaja@neutroni:~$ dep -V
Deployer 6.8.0

Julkaisuasetusten määrittely

Ennen kuin Deployerilla voidaan tehdä julkaisua, on sille määriteltävä julkaisussa tarvittavat asetukset. Tämä määrittely aloitetaan seuraavilla komennolla.

cd ~/public_html/perhekalenteri-dev/
dep init

Tämän jälkeen sinulta kysytään muutama kysymys. Voit jokaisessa kohdassa valita oletusvaihtoehdon painamalla Enter-näppäintä.

  Welcome to the Deployer config generator



 This utility will walk you through creating a deploy.php file.
 It only covers the most common items, and tries to guess sensible defaults.

 Press ^C at any time to quit.

 Please select your project type [Common]:
  [0 ] Common
  [1 ] Laravel
  [2 ] Symfony
  [3 ] Yii
  [4 ] Yii2 Basic App
  [5 ] Yii2 Advanced App
  [6 ] Zend Framework
  [7 ] CakePHP
  [8 ] CodeIgniter
  [9 ] Drupal
  [10] TYPO3
 >

 Repository [git@github.com:fronttikoodaaja/perhekalenteri.git]:
 >

 Contribute to the Deployer Development

 In order to help development and improve the features in Deployer,
 Deployer has a setting for usage data collection. This function
 collects anonymous usage data and sends it to Deployer. The data is
 used in Deployer development to get reliable statistics on which
 features are used (or not used). The information is not traceable
 to any individual or organization. Participation is voluntary,
 and you can change your mind at any time.

 Anonymous usage data contains Deployer version, php version, os type,
 name of the command being executed and whether it was successful or not,
 exception class name, count of hosts and anonymized project hash.

 If you would like to allow us to gather this information and help
 us develop a better tool, please add the code below.

     set('allow_anonymous_stats', true);

 This function will not affect the performance of Deployer as
 the data is insignificant and transmitted in a separate process.

 Do you confirm? (yes/no) [yes]:
 >

Successfully created: /home/koodaaja/public_html/perhekalenteri-dev/deploy.php

Tämä suoritus loi projektin juureen deploy.php-nimisen tiedoston, johon on määritelty projektin julkaisemisessa tarvittavat asetukset. Oletusvastauksilla määritetyt asetukset eivät valitettavasti toimi halutunlaisesti, siksi tätä tiedostoa joutuu vielä muokkaamaan. Avaa projektin juuresta löytyvä asetustiedosto ja tee siihen seuraavat muokkaukset. Voit muokata asetustiedostoa esimerkisi komennolla:

nano ~/public_html/perhekalenteri-dev/deploy.php

1. Muokkaa projektin nimeksi perhekalenteri. Tämä määrittelee samalla kansion, johon julkaistava versio kopioidaan.

   // Project name
   set('application', 'perhekalenteri');
   

2. Kommentoi asetuksista seuraava määritys.

   // [Optional] Allocate tty for git clone. Default value is false.
   // set('git_tty', true);
   

3. Muokkaa host-asetus seuraavanlaiseksi. Tämä määrittelee palvelimen sekä kansion, johon julkaistava versio kopiodaan.

   // Hosts
   host('neutroni.hayo.fi')
       ->set('deploy_path', '~/public_html/{{application}}');
   

4. Poista task('deploy', [-rivin alapuolelta seuraava rivi. Koska julkaistavassa projektissa ei ole käytössä Composerilla asennettuja paketteja, niin pakettien asennukseen liittyvä vaihe poistetaan, jotta julkaisu ei pääty virheeseen.

       'deploy:vendors',
   

Projektin ensimmäinen julkaisu

Nyt Deployer on määritetty, seuraavaksi tehdään ensimmäinen julkaisu. Julkaiseminen tapahtuu yksinkertaisesti komennolla

dep deploy

Komento kysyy sinulta neutroni-käyttäjän salasanaa, koska Deployer tekee julkaisun SSH-yhteyden ylitse. Toisin sanoen skripti ottaa yhteyden samalle palvelimelle samalla käyttäjällä ja kopioi julkaistavat tiedostot tämän yhteyden ylitse. Deployer on suunniteltu tekemään julkaisu toiselle palvelimelle, siksi se toimii näin.

✈︎ Deploying main on neutroni.hayo.fi
➤ Executing task deploy:prepare
✔oodaaja@neutroni.hayo.fi's password:
✔ Executing task deploy:lock
✔ Executing task deploy:release
✔ Executing task deploy:update_code
✔ Executing task deploy:shared
✔ Executing task deploy:writable
✔ Executing task deploy:clear_paths
✔ Executing task deploy:symlink
✔ Executing task deploy:unlock
✔ Executing task cleanup
Successfully deployed!

Nyt kotihakemistosta löytyy myös perhekalenteri-niminen kansio, joka sisältää projektin julkaistun version. Pääset julkaistuun versioon osoitteella https://neutroni.hayo.fi/~tunnus/perhekalenteri.

Julkaisukansio sisältää seuraavat kolme alikansiota:

• current-kansio on linkitetty aina nykyiseen käytössä olevaan julkaisuun, joka löytyy releases-kansion alta. Normaalisti tämä on viimeisin sivustolle tehty julkaisu.

• releases-kansio sisältää julkaistut versiot, esimerkiksi releases/1-kansiossa on ensimmäisen julkaisun tiedostot. Kansiossa olevien julkaisujen määrä riippuu asetusista, Deployer siistii kansiosta vanhempia versiota pois julkaisun yhteydessä.

• shared-kansio sisältää kaikille julkaisuille yhteiset tiedostot. Tämä mahdollistaa esim. sen, että isoja tiedostoja ei kopioida useampaan eri julkaisuun, vaan niitä käytetään shared-kansion alta.

Toisin sanoen, viimeinen virallinen julkaisu löytyy aina osoitteesta http://neutroni.hayo.fi/~tunnus/perhekalenteri/current. Oikeassa tuotantopalvelimessa release-kansio määriteltäisiin sivuston juurihakemistoksi, jolloin käyttäjälle näkyy vain se, mitä on current-kansion alla.

Pienen muutoksen julkaiseminen

Kokeillaan vielä tehdä sivuston etusivulle pieni muutos, joka myös julkaistaan. Muokkaa perhekalenteri-dev-kansiossa olevaa index.php-tiedostoa. Muuta sivun lopussa oleva teksti toiseksi, esimerkiksi

      <div>perhekalenteri by koodaaja</div>

Tarkista menemällä osoitteeseen https://neutroni.hayo.fi/~tunnus/perhekalenteri-dev/, että tekemäsi muutos ei rikkonut sivuston toimintaa. Jos sivu näyttää hyvältä, niin vie muutokset versiohallintaan seuraavilla komennoilla. Ensimmäinen komento pitää huolen, että teet commitin oikeaan projektiin.

cd ~/public_html/perhekalenteri-dev
git add .
git commit -m "deployer-asetukset ja testikorjaus"
git push

Tämän jälkeen voit tehdä julkaisun komennolla:

dep deploy

Komennon suoritus tulostaa saman tulostuksen, kuin edelliselläkin kerralla.

✈︎ Deploying main on neutroni.hayo.fi
➤ Executing task deploy:prepare
✔oodaaja@neutroni.hayo.fi's password:
✔ Executing task deploy:lock
✔ Executing task deploy:release
✔ Executing task deploy:update_code
✔ Executing task deploy:shared
✔ Executing task deploy:writable
✔ Executing task deploy:clear_paths
✔ Executing task deploy:symlink
✔ Executing task deploy:unlock
✔ Executing task cleanup
Successfully deployed!

Erona on se, että releases-kansiosta löytyy nyt kaksi kansiota, ensimmäinen (1) ja toinen (2) julkaisu. Juuressa oleva current-kansio on nyt linkitetty näistä jälkimmäiseen.

GitHub Actions

Sovelluskehityksessä hyödynnetään tänäpäivänä jatkuvaa integrointia (CI, continuous integration) ja jatkuvaa käyttöönottoa (CD, continuous deployment). Tiivistetysti tämä tarkoittaa sitä, että sovelluskehityksessä uuden koodin käyttöönotto on automatisoitu mahdollisimman tehokkaaksi. Automatisointi huolehtii tyypillisesti koodin testaamisen ja sen julkaisemisen.

GitHub sisältää toiminnallisuuden, jolla voi automatisoida näitä sovelluskehityksen työkulkuja. Tätä toiminnallisuutta kutsutaan nimellä GitHub Actions. Vastaavanlaisia palveluita on tarjolla paljon, kuten esimerkiksi Jenkins ja Travis CI.

Seuraavaksi tutustumme lyhyesti siihen, miten edellä määritelty Delpoyer-julkaisu voidaan automatisoida GitHub-palvelussa.

SSH-avaimien määrittely GitHub-repon asetuksiin

Jotta GitHub-palvelin pääsee ottamaan SSH-yhteyden tuotantopalvelimen virkaa toimittavalle neutroni-palvelimelle, on sitä varten luotava ja määriteltävä SSH-avaimet. Nämä avaimet eivät ole samat, kuin aikaisemmin luodut SSH-avaimet, koska seuraavaksi toteutettavassa toimintopolussa SSH-yhteyden suunta on eri. Toisin sanoen syötämme GitHub-palveluun yksityisen avaimen, jolla se pystyy ottamaan turvallisen yhteyden neutroni-palvelimelle.

1. Luodaan ensiksi tarvittavat SSH-avaimet. Suorita seuraava komento neutronin komentorivillä.

   ssh-keygen -t rsa -b 4096 -f ~/.ssh/github-actions
   

   Älä määrittele salasanaa, vaan jätä kumpikin kohta tyhjäksi painamalla Enter-näppäintä. Tämä siksi, että GitHub Actions -työkulussa tuota salasanaa ei pääse syöttämään manuaalisesti. Komennon suorituksen jälkeen sinulta löytyy nyt julkinen avain (~/.ssh/github-actions.pub) ja yksityinen avain (~/.ssh/github-actions).

2. Lisätään julkinen avain niiden avaimien joukkoon, jotka on hyväksytty käytettäväksi kirjautumisessa.

   cat ~/.ssh/github-actions.pub >> ~/.ssh/authorized_keys
   

   Tämä komento lisää julkisen avaimen authorized_keys-tiedoston loppuun. Huomaa, että komennossa kuuluu olla kaksi >-merkkiä. Jos suoritat komennon yhdellä merkillä, niin authorized_keys-tiedoston sisältö tyhjenee ja tilalle tulee github-actions.pub-tiedoston sisältö.

3. Lisätään yksityinen avain GitHub-repon asetuksissa salattuihin tietoihin. Kopioidaan ensin yksityinen avain leikepöydälle. Suorita seuraava komento ja kopioi komennon tulos leikepöydälle. Kopioitava alue alkaa rivillä -----BEGIN OPENSSH PRIVATE KEY----- ja päättyy riviin -----END OPENSSH PRIVATE KEY-----.

   cat ~/.ssh/github-actions
   

   Avaa seuraavaksi GitHubissa repon asetukset, klikkaamalla Settings-linkkiä, joka on linkkirivin oikeassa reunassa.

   
   
   

   Valitse oikean reunan valikosta Secrets and variables -otsikon alta Actions-kohta.

   
   
   

   Klikkaa sivun yläreunassa olevaa New repository secret-nappia.

   
   
   

   Kirjoita Name-kentän arvoksi PRIVATE_KEY, liitä Value-kenttään tämän vaiheen alussa leikepöydälle kopioimasi yksityinen avain ja paina lopuksi Add Secret -nappia.

   
   
   

4. Jotta SSH-yhteys ei jämähdä siihen, että avattava yhteys ei ole luotettu, on myös known_host-tiedoston sisältö selvitettävä. Suorita seuraava komento ja kopioi komennon tulos leikepöydälle.

   ssh-keyscan neutroni.hayo.fi
   

   Lisää uusi salattu tieto painamalla Actions secrets-sivulla New repository secret -nappia. Kirjoita Name-kentän arvoksi KNOWN_HOSTS ja liitä Value-kentään arvoksi edellä leikepöydälle kopiomasi ssh-keyscan -komennon tulos. Paina lopuksi Add secret -nappia.

   
   
   

   Tämän jälkeen sinulla näkyy Repository secrets -listalla kaksi salattua tietoa. Pääset Kynä-ikonia painamalla päivittämään salatun tiedon uuteen. Huomaa kuitenkin, että GitHub ei näytä salattuna tallennettujen tietojen sisältöjä.

   
   
   

5. Viimeisenä vaiheena on vielä pieni muutos Deployer-asetuksiin. GitHub-palvelussa julkaisuskripti suoritetaan eri käyttäjän alaisuudessa, mille se tullaan lopulta kopioimaan neutroni-palvelimella. Jotta Deployer osaa luoda SSH-yhteyden oikealla käyttäjällä, lisätään se tieto vielä määrityksiin. Muokkaa projektin juuressa (~/public_html/perhekalenteri-dev) olevaa deploy.php-tiedostoa. Päivitä tiedostossa Host-määrite seuraavanlaiseksi. Vaihda neutroni-tunnus-tekstin paikalle oma neutroni-tunnukseksi. Jos tunnuksesi olisi koodaaja niin laita se neutroni-tunnus-tekstin paikalle.

   // Hosts
   host('neutroni.hayo.fi')
       ->user('neutroni-tunnus')
       ->set('deploy_path', '~/public_html/{{application}}');
   

   Vie lisäksi tämä muutos GitHub-repoon komennoilla:

   cd ~/public_html/perhekalenteri-dev
   git add .
   git commit -m "deploy.php-tiedoston host päivitetty"
   git push
   

Sovelluksen julkaisu manuaalisesti GitHubista

Toteutetaan ensin työkulku, joka tekee sovelluksen julkaisun, kun se käynnistetään manuaalisesti GitHubin puolella. Työkulut toteutetaan Actions-sivun alle, joten klikkaa reponäkymässä Actions-linkkiä. Näkymässä tarjotaan valmiita työkulkuja, jotka GitHub arvioi soveltuvan projektillesi. Näitä ei tällä kertaa hyödynnetä, vaan klikataan set up a workflow yourself -linkkiä.

Editorikentän yläpuolella kysytään tiedoston nimeä, anna nimeksi deploy-manual.yml.

Laita editorikenttään seuraavat sisällöt jatkossa tulevassa järjestyksessä.

name: Manual deploy to neutroni

Tämä rivi määrittelee työkululle nimen, jolla se näkyy GitHubin toimintalogeissa.

on: 
  workflow_dispatch:

Tämä asetus määrittelee milloin työkulku käynnistyy. workflow_dispatch-arvo määrittelee, että työkulku käynnistetään manuaalisesti.

jobs:
  deploy:
    name: Deployment
    runs-on: ubuntu-latest

Tämä kertoo, että työkulkuun kuuluu Deployment-niminen työ, joka suoritetaan ympäristössä, jossa on Ubuntun viimeisin versio.

    steps:
      - uses: actions/checkout@v3

Työ jaetaan vaiheisiin ja ensimmäinen vaihe on GitHub-repon kopioiminen suoritusympäristöön.

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "8.2"

Työn toinen vaihe on PHP-ympäristön asennus. Tämä asentaa PHP-version 8.2. setup-php-toiminto voi asentaa PHP:n lisäksi paljon muitakin, tarkemmat tiedot tästä löytyy sen dokumentaatiosta.

      - name: Deploy
        uses: deployphp/action@master
        with:
          private-key: ${{ secrets.PRIVATE_KEY }}
          known-hosts: ${{ secrets.KNOWN_HOSTS }}
          dep: deploy
          deployer-version: "6.8.0"

Työn viimeisenä vaiheena on Deployer-skriptin suoritus. Skriptille annetaan syötteenä aiemmin GitHubin repoon salattuna tallennetut tiedot yksityisestä avaimesta ja luotetuista palvelimista. Huomaa, että sercets-sanan perässä olevien tunnisteiden tulee täsmätä GitHub-repon Action secrets -sivulla olevien nimien kanssa. Käytettäväksi deployer-versioksi määritellään sama kuin neutronilla.

Huomaa myös, että tässä ei määritellä tarkemmin minne sovellus julkaistaan, nämä määritykset löytyvät Deployerin deploy.php-tiedoston asetuksista.

Tässä on lisättävä asetustiedoston sisältö vielä kokonaisuudessaan:

name: Manual deploy to neutroni

on: 
  workflow_dispatch:

jobs:
  deploy:
    name: Deployment
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "8.2"

      - name: Deploy
        uses: deployphp/action@master
        with:
          private-key: ${{ secrets.PRIVATE_KEY }}
          known-hosts: ${{ secrets.KNOWN_HOSTS }}
          dep: deploy
          deployer-version: "6.8.0"

Tallenna määritystiedosto klikkaamalla vihreää Start commit -nappia ja avautuvasta ikkunasta Commit new file -nappia. Halutessasi voit kirjoittaa commitille kuvaustekstin.

Testataan seuraavaksi edellä lisäämämme työkulku suorittamalla se manuaalisesti. Valitse ensin GitHubin toimintolinkeistä Actions, klikkaa aktiiviseksi Manual deploy to neutroni-työkulku ja klikkaa Run workflow-valikon alta Run workflow-nappia.

Tämä käynnisti työkulun ja työkulkujen suorituslistaan ilmestyy uusi rivi, joka kertoo, että työkulkua suoritetaan.

Pienen hetken päästä työkulku on suoritettu ja tieto sen onnistumisestä näkyy työkulun edessä olevasta ikonista. Vihreä tarkoittaa, että työkulun suoritus onnistui, punainen puolestaan tarkoittaa työkulun suorituksen epäonnistumista.

Työkulun otsikkoa klikkaamalla pääset näkemään tarkempaa tietoa työkulusta. Kooste sivulla näkee suoritusajan lisäksi myös työkulun osatyöt.

Osatyön nimeä klikkaamalla pääsee näkemään miten osatyön suoritus onnistui. Esimerkkitapauksessa Deploy-vaiheen suoritus vei 24 sekuntia. Vaiheen päällä klikkaamalla saa vielä lisää tietoa vaiheen aikana suoritetuista toiminnoista.

Sivustolle, jonne sovellus julkaistiin on tullut uusi release-julkaisu 3.

GitHubin Releases-julkaisut

GitHubissa on myös oma Releases-ominaisuus, jolla voidaan julkaista sovelluksesta uusi, virallinen versio. Tämä on täysin eri kuin Deployerissa oleva releases-käsite, yhteistä niillä on lähinnä niiden nimi. Seuraavaksi tutustumme siihen, miten GitHubissa tehdään uusi Release-julkaisu.

Klikkaa GitHub-repon tiedostonäkymän oikeassa reunassa olevan Releases-otsikon alta Create a new release-linkkiä.

Klikkaa avautuvasta ikkunasta ensin Choose a tag-nappia, kirjoita kenttää teksti v1.0.0 ja paina lopuksi tekstin alapuolella olevaa + Create a new tag: v1.0.0 on publish -vaihtoehtoa.

Tagin määrittelyn jälkeen voit kirjoittaa otsikkoon ja kuvaukseen haluamasi tekstit. Kuvauksessa voit muotoilla sisältöä Markdown-merkkauksella. Kun olet tyytyväinen sisältöön, niin paina lomakkeen alareunassa olevaa Publish release-nappia.

Tämän jälkeen GitHub-projektisi sivuilla näkyy uusi julkaisu.

Sovelluksen automaattisen julkaisun työnkulku

Seuraavaksi teemme GitHub Actions -työnkulun, joka tekee uuden julkaisun aina, kun GitHubiin tehdään uusi release-julkaisu. Työnkulku on käytännössä hyvin pitkälle sama kuin manuaalisessa käynnistyksessä, ainoastaan käynnistysehto muutetaan.

Aktivoi ensin Actions sivun yläreunan toimintolinkeistä, aloita uuden työnkulun luominen painamalla New workflow-nappia ja klikkaamalla set up a workflow yourself-linkkiä.

Anna työnkulun nimeksi deploy-release.yml ja syötä työnkuluksi seuraava teksti:

name: Release deploy to neutroni

on:
  release:

jobs:
  deploy:
    name: Deployment
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "8.2"

      - name: Deploy
        uses: deployphp/action@master
        with:
          private-key: ${{ secrets.PRIVATE_KEY }}
          known-hosts: ${{ secrets.KNOWN_HOSTS }}
          dep: deploy
          deployer-version: "6.8.0"

Tallenna määritystiedosto klikkaamalla vihreää Start commit -nappia ja avautuvasta ikkunasta Commit new file -nappia. Halutessasi voit kirjoittaa commitille kuvaustekstin.

Automaattisen työnkulun testaaminen

Seuraavaksi testaamme automaattisen työnkulun toimintaa tekemällä ensin sovellukseen kaksi muutosta ja tekemällä muutoksista uuden Release-julkaisun.

1. Ensimmäisessä muutoksessa lisäämme uuden fonttivaihtoehdon käytettäviin fontteihin. Muokkaa projektin juuressa (~/public_html/perhekalenteri-dev) olevaa globals.php-tiedostoa. Muokkaa $headerfonts-taulukon sisältöä niin, että taulukon loppuosa osa seuraavanlainen. Huomaa myös lisätä alkuperäisen taulukon viimeisen alkion loppuun tullut pilkku.

       ... taulukon alku on sama 
       "sigmarone" => array(
         "name" => "Sigmar One",
         "url"  => "https://fonts.googleapis.com/css2?family=Sigmar+One&display=swap"),
       "titanone" => array(
         "name" => "Titan One",
         "url"  => "https://fonts.googleapis.com/css2?family=Titan+One&display=swap")
     );
   

   Testataan sivun toiminta osoitteessa https://neutroni.hayo.fi/~tunnus/perhekalenteri-dev, valitaan otsikkofontiksi Titan One ja avataan kalenterisivu.

   
   
   

   Viedään tämä muutos versiohallintaan. git pull -komento noutaa GitHub-reposta sinne tehdyt muutokset paikallisesti. Yhdistämisen saattaa avata sinulle editorin, jossa sinulta kysytään yhdistämisen commit-tekstiä, voit hyväksyä tarjotun tekstin tallentamalla ja poistumalla editorista.

   cd ~/public_html/perhekalenteri-dev
   git add .
   git commit -m "Titan One lisätty otsikkofonttilistalle"
   git pull 
   git push
   

2. Muutetaan seuraavaksi nimilistaa niin, että kentässä näkee useamman nimen saman aikaisesti. Muokkaa projektin juuressa (~/public_html/perhekalenteri-dev) olevaa index.php-tiedostoa. Muokkaa Perheenjäsenet-kohdan merkkausta seuraavanlaiseksi:

           Perheenjäsenet:
           <textarea name="names" rows="5"><?= $defaultnames ?></textarea><br>
   

   Testataan jälleen kerran muutoksen toimivuutta menemällä osoitteeseen https://neutroni.hayo.fi/~tunnus/perhekalenteri-dev. Syötekenttä perheenjäsenten nimien syöttämiseen on nyt viisi riviä korkea.

   
   
   

   Viedään tämä muutos versiohallintaan. git pull -komento ei tee tällä kertaa mitään, koska GitHubin repoon ei ole tullut uutta sisältöä, jota ei olisi paikallisesti.

   cd ~/public_html/perhekalenteri-dev
   git add .
   git commit -m "Perheenjäsenet-tekstialueen korkeutta lisätty"
   git pull 
   git push
   

Näiden kahden muutosten jälkeen voimme tehdä GitHubissa uuden release-julkaisun. Klikkaa GitHub-projektin pääsivun oikeassa laidassa olevaa Releases-otsikkoa.

Klikkaa Releases-sivulla olevaa Draft a new release -nappia.

Klikkaa Choose a tag -nappia, kirjoita kenttään teksti v1.0.1 ja klikkaa Create a new tag -kentän alapuolelta. Kirjoita haluamasi sisältö julkaisun otsikoksi ja tekstiksi. Paina lopuksi Publish release-nappia.

Kun menet GitHub-projektin Actions-sivulle, niin näet käynnistyikö julkaisu automaattisesti ja onnistuiko julkaisun tekeminen.

Loginäkymästä ilmenee, että release-julkaisu käynnisti työkulun kolmeen kertaan, joista yksi onnistui (published) ja loput kaksi epäonnistuivat (created ja released). Korjataan työkulkua niin, että työnkulku suoritaan ainoastaan silloin, kun uusi release-julkaisu tehdään julkiseksi. Muokkaa .github/workflows-kansiossa olevaa deploy-release.yml-tiedostoa. Muuta työnkulun käynnistysmäärittely seuraavanlaiseksi:

on:
  release:
    types: [published]    

Hyväksy muutos klikkaamalla Start commit -nappia, kirjoita haluamasi commit-teksti ja klikkaa lopuksi Commit changes-nappia.

Voit testata muutoksen toimintaa käymällä muokkaamassa viimeisimmän Release-julkaisun tietoja ja hyväksymällä muutokset klikkaamalla Update release-nappia. Tietoihin itsessään ei tarvitse tehdä muutoksia. Tämä käynnistää työnkulun ainoastaan kerran.