Version Control
Version control is a recommended way of managing software code or scripts, configurations and their different versions.
Version control enables collaboration between different team members and allows development, test and production code to be managed simultaneously in different scenarios.
General information about version control and why it should be used:: https://www.atlassian.com/git/tutorials/what-is-version-control.
Transparency as a Starting Point
The University of Helsinki has decided to release the code openly. The code of the final software should be published openly on GitHub at the latest. Working versions and e.g. maintenance scripts etc. do not need to be released.
Additional reading: Principles of Open Source
Check also the application guidelines: Open Source - Instructions for Application
Version Control Systems
In the University of Helsinki we use three different version control system:
- Two local GitLabs
- https://version.helsinki.fi/ - public local GitLab CE -instance.
- https://scm.it.helsinki.fi/ - restricted local GitLab CE -instance
- GitHub
GitHub
It is advisable to create an open GitHub project in cases where you want to gain recognition and international visibility for the project, or if the project is intended for collaboration with private entities.
According to current practice, the IT Center (TIKE) prefers open source, so it is desirable that completed software projects are also set up on an open GitHub.
GitHub accounts
- It is not mandatory for the staff of the University of Helsinki to create their own GitHub account for work purposes, but they may do so if they wish.
- It is recommended that staff accounts are linked to the relevant GitHub organisation.
- You can request the link from your own organisation's support.
- The use of two-factor authentication (2FA) is strongly recommended.
- For organisation owners, 2FA is mandatory. It is recommended that teams also adopt the practice of making 2FA mandatory for repository admins.
Remember to keep recovery codes in a safe place!
GitHub repositories
- The members of an organisation may create new open repositories.
- The repository must meet at least the following requirements:
- The repository must be connected to the University of Helsinki, it should contain e.g. a university project or application
- There should be a repository description and README.
- Licensing model should be defined (e.g. CC BY-SA 4.0)
- The repository should have responsibles, who have administration rights to the repository.
- When a repository is no longer actively maintained, this information should be updated in the README file and the repository should be archived.
- There are three levels of access rights:
- Admin: full control over the repository, including access level management.
- Write: the access needed by the developer, users can contribute to the repository by creating, editing or deleteting branches and files. They can also submit and merge pull requests and handle issue tracking.
- Read: users can view repository's content and clone it, they can comment on issues and pull requests but cannot make changes to the repository's code or settings.
- When managing access rights, it is recommended to primarily use GitHub Teams.
- Organisation members can create teams, becoming team administrators.
Team administrators can add organisation members to teams.
Note: External users cannot be added to the organisation. Membership can be requested via the organisation's support address (versionhallinta@helsinki.fi) for staff and, for example, long-term consultants.
- Individual user permissions can also be granted if necessary, e.g., to provide access to developers outside the University of Helsinki.
- There is a limited number of private repositories available, so version.helsinki.fi GitLab is recommended for a standard private repository.
- If GitLab is not a suitable option for a private project for some reason (e.g., there is an integration dependent on GitHub), a limited number of private repositories can also be created on GitHub.
Administration and support
- UniversityofHelsinki-organisation administration can be contacted with email: versionhallinta@helsinki.fi
- UH-StudentServices-organisation administration: Antero Aunesluoma
GitLab
A version control service supported and maintained by IT-Center, suitable for both internal and shared projects. Recommended for software projects and scripts that require restricted repositories.
Note: Current policy recommends that source code is shared in a public and open GitHub repository.
GitLab is recommended if you need restricted repositories or features such as GitLab's CI/CD.
There is no limit on the number of projects per user.
Logging into system
- Primarily use the university's AD credentials to log in.
If a consultant does not have a helsinki.fi email address but instead has an external domain email address (e.g., gofore.com, visma.com, druid.fi), the domain must be specifically allowed.
- Contact the administration (atk-verkkopalvelut@helsinki.fi) and request that the domain be added to the allowed domains if it is not already there.
- Note that the email address of a consultant's university AD account can point to an external domain! GitLab always checks the email domain during login regardless of the login method.
- However, if the consultant is a former university student, for example, they will usually already have a university email address in their records that allows them to sign in. This can cause confusion if one consultant can log in directly and another cannot.
- It is also possible to register external accounts (xyz@foo.com), but their domains must also be specifically allowed, see above.
- The use of two-factor authentication (2FA) is strongly recommended.
Please notice
- when you push or pull content into repository, you should use SSH-key.
- If you try password authentication too many times, your IP-address will be banned. If your address is banned, please contact maintenance.
- Determine the version control practices specific to the team/project, for example:
- Code branching. Are there separate development, testing, and production branches?
- Code merging policy. Are merge requests used?
- Commit messages for code changes, how is version numbering done?
Getting Started Briefly
- Install the GIT tool
- Generate an SSH-key for yourself
- Link your SSH key’s public part (‘key_name.pub’) to your GitLab account in settings. Instructions
- To simplify authentication in the future, consider using an SSH agent.
- New Project:
- Create a new empty project in GitLab
- Create a local GIT project
- Link them together using GIT
- You can also clone an existing project from GitLab to your machine, which automatically connects the local version to version.helsinki.fi.
- HTTPS: git clone https://version.helsinki.fi/projectName/repo.git
- SSH: git clone git@version.helsinki.fi:projectName/repo.git
Resources
- GitLab documentation: https://docs.gitlab.com/ee/README.html
- CI/CD pipeline (Continuous Integration/Continuous Deployment): https://docs.gitlab.com/ee/ci/
Administration
- IT Center Web And Collaboration Services team, atk-verkkopalvelut@helsinki.fi
For Special Cases: More Restricted GitLab
Important to note
- The SCM GitLab instance is not accessible from external networks and is not under SSO authentication; it requires a separate, local user account.
- It is used for a few projects/services with higher security levels.
Inquiries: Tapio piironen
Problem cases
Common troubleshooting issues and their solutions.
SSH Key and connections
On a Windows machine the command
PS C:\Users\me\Desktop> ssh-add ~/.ssh/my-rsa-key.key
gives the error
Error connecting to agent: No such file or directory
In this case, make sure the SSH Agent service is up and running
GIT instructions
GIT is a distributed version control system for managing source code changes. It enables, among other things, the handling of different code versions and the maintenance of historical information.
Installation
- GIT installation instructions: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
- After the installation add the git-command into your PATH (usually this happens automatically)
Windows installation
- GIT for Windows: https://gitforwindows.org/
After the installation give the following configuration command:
PS C:\Users\me> git config --global core.sshCommand "'C:\Windows\System32\OpenSSH\ssh.exe'"
With this Configuration Git uses Windows-native OpenSSH instead of its own.
Configure your name and mail address to the GIT:
PS C:\Users\mä> git config --global user.name "Jesse Faden" PS C:\Users\mä> git config --global user.email "jesse.faden@fbc.gov"
Usage
When the installation is complete and the command is in the PATH, you can use GIT from the command line (CMD, Bash, PowerShell)
- GIT command cheat sheet: https://training.github.com/downloads/github-git-cheat-sheet.pdf
GUIs are available, too:
- List of downloadable graphical GIT interfaces: https://git-scm.com/downloads/guis
Commonly used code editors also provide their own tools for version control, for example:
- Visual Studio Code: https://code.visualstudio.com/docs/editor/versioncontrol
- Intellij IDEA: https://www.jetbrains.com/help/idea/version-control-integration.html
Additional material
- What is GIT: https://www.atlassian.com/git/tutorials/what-is-git
- Examples and training: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html
- More training (in Finnish): https://tkt-lapio.github.io/git/
Additional tools
Windows:
- GIT-support to PowerShell: https://github.com/dahlbyk/posh-git
- SSH-support to PowerShell: https://github.com/dahlbyk/posh-sshell
Linux:
- GIT support to Bash: https://github.com/magicmonty/bash-git-prompt
Mac:
- GIT support to Bash: https://github.com/magicmonty/bash-git-prompt