Versionhallinta

Last modified by ovanajas@helsinki_fi on 2024/02/07 06:35

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

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

Helsingin yliopistolla on useita virallisia GitHub-organisaatioita.

https://github.com/UniversityofHelsinki - HY:n yleinen GitHub-organisaatio, jonka hallinnoinnista vastaa tietotekniikkakeskus.

Lisäksi eri laitoksilla ja ryhmillä on omia, rajatumman käytön GitHub-organisaatioita, kuten:

https://github.com/NatLibFi - Kansalliskirjasto
https://github.com/luomus - Luonnontieteellinen keskusmuseo
https://github.com/UH-StudentServices - Opetus- ja opiskelijapalveluiden (OPA) oma GitHub-organisaatio.

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 pyyttää 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

https://version.helsinki.fi

Tiken virallinen versionhallintapalvelu, joka soveltuu niin talon sisäisiin kuin jaettuihin projekteihin. Suositellaan ohjelmistoprojekteille ja scripteille, 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

Tarkemmat ohjeet: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html

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

https://scm.it.helsinki.fi

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&#x3e; 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ä&#x3e; 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ä&#x3e; git config --global user.name "Meikä Läinen"PS C:\Users\mä&#x3e; 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: