Versionhallinta on suositeltava tapa ylläpitää ohjelmakoodia tai scriptejä ja niiden eri versioita.

Versionhallinta helpottaa yhteistyötä eri tahojen välillä ja mahdollistaa eri tilanteessa olevan kehitys-, testi- ja tuotantokoodin samanaikaisen käsittelyn.

Yleisesti versionhallinnasta ja miksi sitä kannattaa käyttää: https://www.atlassian.com/git/tutorials/what-is-version-control

• Avoimuus lähtökohtana
• HY:n Versionhallintajärjestelmät
  • GitHub
    • GitHub-tunnukset
    • GitHub-repositoriot
    • Ylläpito ja tuki
  • GitLab
    • • Tunnistautuminen
      • Huomioitavaa
      • Käyttöönotto lyhyesti
      • Materiaalia
      • Ylläpito
  • Erikoistapauksiin: tiukemmin rajattu GitLab
    • • Huomioitavaa
  • Ongelmatapauksia
    • SSH-Avain ja yhteydet
• GIT ohjeet ja käyttöönotto
  • • • Asennus
        • Windows asennus ja vinkkejä
      • Käyttö
      • Materiaalia
      • Näppäriä lisätyökaluja

Avoimuus lähtökohtana

Helsingin yliopistolla on tehty päätös koodin avoimesta julkaisusta. Viimeistään valmiin ohjelmiston koodi tulisi julkaista GitHubissa avoimesti. Työversiota ja esim. ylläpitoskriptejä tms ei tarvitse julkaista.

Lue: Avoimen lähdekoorin periaatteet

Tutustu myös soveltamisohjeisiin: Avoin lähdekoodi - Soveltamisohjeet

HY:n Versionhallintajärjestelmät

GitHub

GitHubiin on suotuisaa perustaa julkinen ja avoin projekti sellaiselle koodille, joka ei sisällä salattua tai muuten herkkäluontoista materiaalia.

TIKE suosii nykyisen käytännön mukaan avointa lähdekoodia, joten on toivottavaa, että valmiit ohjelmistoprojektit perustetaan myös avoimeen GitHub:iin

Julkiset GitHub-repot soveltunevat projekteille, joille on erityisen tärkeää GitHubin tarjoama tunnettavuus ja kansainvälinen näkyvyys.

GitHub-tunnukset

• Helsingin yliopiston henkilökunnan ei ole välttämätöntä luoda työkäyttöön omaa GitHub-tunnusta, mutta näin voi halutessaan tehdä
• Henkilökunnan tunnukset kannattaa liitää osaksi käytettyä GitHub-organisaatiota.
  • Liitosta voi pyytää organisaation tuki-osoitteesta.
• Kaksivaiheisen tunnistautumisen (2FA) käyttö on on vahvasti suositeltua.
  • Organisaation omistajille 2FA on pakollista. Tiimeille suositellaan käytäntöä, jossa repositorion admineilla 2FA on myös pakollinen.
  • Muista tallettaa palautuskoodit turvalliseen paikkaan!

GitHub-repositoriot

• Organisaation jäsenet voivat luoda uusia avoimia repositorioita.
• Vaatimuksina on vähintään:
  • Liittyy Helsingin yliopistoon, esim. HY:n projekti tai sovellus.
  • Kuvaus ja README, joka kertoo perustiedot tarkoituksesta.
  • Lisenssi on määritetty.
  • Vastuuhenkilö(t), joilla on hallintaoikeus repositorioon ja jotka vastaavat repositorion tietojen ajantasaisuudesta.
• Kun repositoriota ei enää aktiivisesti ylläpidetä, tulee tieto tästä päivättää README-tiedostoon ja arkistoida repositorio. 
• Repositorioon voidaan määrittää kolmen tasoisia pääsyoikeuksia:
  • Admin: kaikki toiminnallisuudet, mukaan lukien oikeuksien hallinta ja repositorion poisto.
  • Write: perus kehittäjän tarvitsemat oikeudet, ml. koodin julkaiseminen.
  • Read: vain lukuoikeudet.
• Pääsyoikeuksien hallinnassa kannattaa käyttää ensisijaisesti GitHub-tiimejä.
  • Organisaation jäsenet voivat luoda tiimejä, jolloin heistä tulee tiimin ylläpitäjiä.
  • Tiimin ylläpitäjät voivat lisätä organisaation jäseniä tiimeihin.
    • Huom. ulkopuolisia ei voi lisätä organisaatioon. Henkilökunnalle ja esimerkiksi pitkäaikaisille konsulteille voi pyytää jäsenyyttä organisaation tuki-osoitteesta.
  • Tarpeen mukaan voidaan lisätä myös yksittäisille käyttäjille oikeuksia. Esim. pääsy HY:n ulkopuolisille kehittäjälle.
• Privaattirepoja on rajallinen määrä kummassakin organisaatiossa, joten tavanomaiseen privaattirepoon GitLab (version.helsinki.fi) on suositeltavampi.
  • Jos GitLab ei syystä tai toisesta ole yksityiselle projektille suotuisa vaihtoehto (esim. jokin GitHubista riippuvainen integraatio), voi GitHub:iin perustaa myös rajatun määrän privaatteja repoja.

Ylläpito ja tuki

• UniversityofHelsinki-organisaation adminit tavoittaa osoitteesta: versionhallinta@helsinki.fi
• UH-StudentServices-organisaation admineita: mm. Antero Aunesluoma

GitLab

Tiken virallinen versionhallintapalvelu, joka soveltuu niin talon sisäisiin kuin jaettuihin projekteihin. Suositellaan ohjelmistoprojekteille ja skripteille, joissa on tarve rajatuille repoisitorioille.

• Huom. Nykyinen linjaus suosittelee lähdekoodin jakoa julkisessa ja avoimessa GitHub-repositoriossa.
• GitLabia kannattaa käyttää, jos tarvitsee rajattuja repositoroita tai GitLabin CI/CD yms. ominaisuuksia.

Käyttäjäkohtaista projektien määrää ei ole rajoitettu.

Tunnistautuminen

• Kirjautuminen ensisijaisesti HY:n AD-tunnuksilla
• Jos konsultilla ei ole helsinki.fi-sähköpostiosoitetta (=tyypillisin tapaus), vaan sähköpostiksi on asetettu ulkopuolinen domain (esim. gofore.com, visma.com, druid.fi...), sen domain on erikseen sallittava.
  • Ota yhteys ylläpitoon (atk-verkkopalvelut@helsinki.fi) ja pyydä domainin asettamista sallittuihin domaineihin jos se ei sielä vielä ole.
  • Tämä siis pätee, vaikka konsultilla on HY:n AD-tunnus! GitLab tarkastelee kirjautumisissa aina sähköpostidomainia riippumatta kirjautumistavasta.
  • Jos konsultti kuitenkin on esim. entinen HY:n opiskelija, hänellä tyypillisesti on HY-sähköposti tiedoissaan valmiina, jolloin kirjautuminen onnistuukin... tämä voi tuottaa hämmennystä, jos joku konsultti pääsee suoraan kirjautumaan ja joku toinen ei.
• Myös ulkopuolisia tunnuksia (xyz@foo.com) on mahdollista rekisteröidä, mutta niidenkin domainit on erikseen sallittava, ks. yllä.
• Vain erikoistapauksissa GitLab-instanssiin luotavalla paikallisella tunnuksella.
• Kaksivaiheisen tunnistautumisen (2FA) käyttö on on vahvasti suositeltua.

Huomioitavaa

• Kun repoon puskee koodia tai sitä lataa omalle koneelle, on käytettävä SSH-avainta.
  • Jos yrität käyttää salasanalla tunnistautumista liian monta kertaa, IP-osoitteesi torjutaan. Jos osoitteesi on torjuttu, ota yhteyttä ylläpitoon.
• Selvitä tiimi-/projektikohtaiset versionhallinnan käytännöt, esim:
  • Koodin haaroitus (branch). Onko erikseen kehitys-, testi- ja tuotantohaarat?
  • Koodin yhdistelypolitiikka (merge). Käytetäänkö merge-requesteja?
  • Koodimuutosten viestit (commit message), versionumerointi?

Käyttöönotto lyhyesti

• Asenna GIT-työkalu
• Generoi itsellesi SSH-avain
• Liitä SSH-avaimen julkinen puolisko ('avaimen_nimi.pub') käyttäjällesi GitLab:in asetuksissa. Ohje
  • Tunnistautumisen helpottamiseksi jatkossa, kannattaa käyttää SSH-agenttia

• Uusi projekti:
  • Luo uusi tyhjä projekti GitLab:iin
  • Luo paikallinen GIT-projekti
  • Liitä ne toisiinsa GIT:in avulla

• Voit myös kloonata GitLab:ista olemassa olevan projektin koneellesi, jolloin paikallinen versio on automaattisesti liitetty version.helsinki.fi:hin.
  • HTTPS: git clone https://version.helsinki.fi/projektinNimi/repo.git
  • SSH: git clone git@version.helsinki.fi:projektinNimi/repo.git

Materiaalia

• For English instructions, see the IT for Science support group's guide to registering and general use: Version.helsinki.fi GitLab server
• GitLab dokumentaatio: https://docs.gitlab.com/ee/README.html
• CI/CD pipeline (jatkuva integraatio / jatkuva kehitys): https://docs.gitlab.com/ee/ci/

Ylläpito

• TIKE:n Verkkpalvelut, atk-verkkopalvelut@helsinki.fi

Erikoistapauksiin: tiukemmin rajattu GitLab

Huomioitavaa

• Tämä GitLab-instanssi ei ole ulkoverkosta saavutettavissa eikä SSO-autentikoinnin piirissä vaan siihen tarvitaan erillinen, paikallinen käyttäjätunnus.
•  Sitä käytetään muutamiin korotetun tietoturvatason projekteihin/palveluihin.

Tiedustelut: Tapio piironen

Ongelmatapauksia

Yleisiä ongelmatapauksia ja ratkaisuja niihin.

Tämä osio on vielä keskeneräinen. Uusia ongelmatapauksia saa lisätä vapaasti.

SSH-Avain ja yhteydet

Windows-koneella komento

PS C:\Users\mä\Desktop> ssh-add ~/.ssh/mun-rsa-avain.key 

sanoo

Error connecting to agent: No such file or directory

Tällöin katso, että SSH-agenttipalvelu on enabloitu ja päällä

GIT ohjeet ja käyttöönotto

GIT on hajautettu versionhallintajärjestelmä lähdekoodimuutosten hallintaan. Se mahdollistaa mm. eri koodiversoiden käsittelyn ja historiatiedon ylläpidon.

Asennus

Ottaaksesi GIT:in käyttöön, se on ensin asennettava koneelle.

• GIT asennusohjeet: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
• Asennuksen jälkeen, lisää GIT:in asennus PATH:iin (lisätään yleensä automaattisesti)

Windows asennus ja vinkkejä

• GIT for Windows: https://gitforwindows.org/

Asennuksen jälkeen Windows-koneilla kannattaa lausua:

PS C:\Users\mä> git config --global core.sshCommand "'C:\Windows\System32\OpenSSH\ssh.exe'"

Tällöin Git käyttää Windows-featurena asennettua OpenSSH:ta eikä omaansa.

Jos teet kehitystyötä kyseisellä koneella, kannattaa oma nimi ja sähköposti määritellä GIT:iin seuraavasti:

PS C:\Users\mä> git config --global user.name "Meikä Läinen"PS C:\Users\mä> git config --global user.email "email@example.com"

Käyttö

Kun GIT on asennettu ja lisätty PATH:iin, sitä voi käyttää suoraan komentoriviltä (esim. CMD, Bash, PowerShell).

• GIT-komentojen lunttauslista löytyy esimerkiksi täältä: https://training.github.com/downloads/github-git-cheat-sheet.pdf

Vaihtoehtoisesti GIT:iä voi käyttää myös graafisin työkaluin.

• Lista ladattavista graafisista työkaluista: https://git-scm.com/downloads/guis
  • Osaan ylläolevista joista puuttuu virallinen Linus tuki, kuten Github Desktoppiin, on epäviralliset versiot myös Linuxille.

Yleisesti käytettävät koodieditorit tarjoavat myös omat työkalunsa versionhallinnan käyttöön, esim:

• Visual Studio Code: https://code.visualstudio.com/docs/editor/versioncontrol
• Intellij IDEA: https://www.jetbrains.com/help/idea/version-control-integration.html

Materiaalia

• Yleinen kuvaus: https://www.atlassian.com/git/tutorials/what-is-git
• Esimerkkejä ja harjoitteita: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html
• Lisää harjoitteita (suomeksi): https://tkt-lapio.github.io/git/

Näppäriä lisätyökaluja

Windows:

• GIT-tuki PowerShelliin: https://github.com/dahlbyk/posh-git
• SSH-tuki PowerShelliin: https://github.com/dahlbyk/posh-sshell

Linux:

• GIT-tuki Bashiin: https://github.com/magicmonty/bash-git-prompt

Mac:

• GIT-tuki Bashiin: https://github.com/magicmonty/bash-git-prompt