Skip to content

Version management

Responsible software development cannot be done without sound version control. Fortunately, there are excellent tools because that can be done without much extra effort. There are several widely used systems, but of the most mature implementations, especially git is very popular these days. Git has hereby displaced subversion (svn) from the first place. On Linux systems, git is mainly used via command line instructions. On Windows systems, you mostly see GUI implementations, such as tortoisegit.

General Principles – do's and don'ts

  • Apply version control to all files needed to assemble the application, the so-called source files.
  • Ensure that the software is managed in a tidy and orderly manner.
  • Avoid using (temporary) copies to work on the software. New features and tryouts can be developed in so-called branches.
  • Try to ensure that the central repository contains a working version of the application. This is especially important for the so called master branch. You can use git and other tools to update intermediate versions very frequently in the local repository for your own use (preferably in a feature or development branch).
  • Prevent temporary files, such as compiled versions of source files, from being included in the repository.
  • Prevent (example) data sets from becoming part of the software repository. If necessary, data sets can be distributed through appropriate channels. Small sample data sets can be included in a separate repository if necessary.
  • Prevent privacy-sensitive information from being included in the source code. This is because in a version control program such information usually cannot be removed.
  • Never include credentials (login names, passwords, ...), passcodes, TLS certificates, server names or other security-related information in the repository.
  • Prefer local (Amsterdam UMC) solutions over publicly available cloud solutions. In other words: start your software development project by creating a project in https://gitlab.amc.nl/. If necessary, a local repository can be cloned to an external provider at any time.
  • Make sure that the ownership of your code repository at https://gitlab.amc.nl/ is shared with, or transferred to, relevant colleagues before the end of your contract.

Git and connecting your Git account to Helios

At the AMC-side, there is a Git implementation called gitlab (accessible at https://gitlab.amc.nl/). Outside of the hospital domain, there are popular cloud-based systems available, like github.com (for example https://github.com/amsterdam-umc-mri and https://github.com/AmsterdamUMC). An account for gitlab.amc.nl can be requested via the service desk of the central Dienst ICT. Gitlab allows the use of groups, which offer role-based access to groups of repositories. This makes it easier to share common source code within and between research groups. For the RNG department there is an existing group hierarchy at https://gitlab.amc.nl/rng (contact rng-ict-research-support@amsterdamumc.nl for access and membership). The git client is already installed on the linux servers. It is often convenient to have a SSH private-public key pair available and register the public part in your git(lab) profile. Keep the private part safe and place it in your ~/.ssh folder on the linux server.

An important difference between git and for example svn, is that git is not organized around a central repository. Instead, git actually has at least two repositories. A local (personal) database containing a complete version history of your local copy of the source files. And a second so-called remote repository, which allows changes to be exchanged with co-developers and enables source code to be distributed.

If you use git as version control system for your code, you can use SSH keys to communicate securely with Gitlab from Helios.

1. Check if you have an existing SSH key pair

cd ~
cd .ssh/

If this directory does not exist, you haven’t used ssh before.

2. Generate a new SSH key pair

ssh-keygen -t ed25519 -C "adesitter helios"
  • Press enter. Accept the suggested filename and directory.
  • Enter a passphrase if you like; you don't see the text you type
  • Public and private key are generated.

3. Add your SSH key to your GitLab account

Copy the contents of your public key file:

cat ~/.ssh/id_ed25519.pub
  • Copy the printed value.
  • Sign in to Gitlab (https://gitlab.amc.nl/)
  • On the left sidebar, select your avatar.
  • Select Edit Profile.
  • On the left sidebar, select SSH Keys.
  • Select Add new key (right corner of your screen).
  • In the Key box, paste the contents of your public key. If you manually copied the key, make sure you copy the entire key.
  • In the title box, type a description like "Helios cluster”.
  • Select Add key.

4. Add config file

touch ~/.ssh/config

Add these settings to your file:

Host gitlab.amc.nl
IdentityFile ~/.ssh/id_ed25519
ProxyCommand /appdata/software/apps/corkscrew/bin/corkscrew endpoint-proxy-a.umcinfra.nl 3128 %h %p

5. Verify that you can connect

ssh -T git@gitlab.amc.nl
  • If this is the first time you connect, you probably should verify the authenticity of the GitLab/GitHub host.
  • Are you sure you want to continue connecting (yes/no)? yes
  • Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hosts.
  • Type yes and press Enter.

Good starting points for learning Git

Note

Never include privacy-sensitive information, credentials, passcodes, TLS certificates, server names or other security-related information in the repository. Prefer local (Amsterdam UMC) solutions over public cloud solutions. Share or transfer repository ownership to relevant colleagues before your contract ends.