Cloud Development Platforms#
A development platform (sometimes called a Forge) is a software application for managing the software development lifecycle.
The most well known services are:
At ICHEC we currently use an internally hosted GitLab instance for code development.
We also have some repositories for public documentation and training material hosted on GitHub.com.
This section gives some tips for setting up a new project or managing an exsting one in GitLab.
Creating a repository#
When creating a repository you should consider whether it belongs to an ICHEC ‘theme’, e.g. Quantum or Performance and if so create a repository under one of these groups. This may require discussion with the theme/activity lead. If it doesn’t fit under an existing one you could could up with a broad theme to place it under, ideally avoiding creating projects at the ‘top level’.
Structuring the repo#
The repo should have a README at the top level, with a description of the project and contact details for it.
A basic overall structure can be something like:
/src # source code
/test # test code
/infra # scripts, including build and deployment tooling
/docs # documentation
/examples # example uses of whatever is in 'source code'
.gitignore
.GitLab-ci.yml
REAMDE.me
LICENSE
You may want to consider choosing a LICENSE also.
Use .gitignore to avoid noise files (like DStore on Mac or IDE generated files) getting checked into the repo. Use .GitLab-ci.yml to control the CI/CD pipeline.
GitLab options#
GitLab allows control over how others interact with the repository.
You should have at least a main or master branch which will be automatically generated. You may also have other branches, such as a devel one as a precursor to master. You should restrict direct ‘pushes’ to master and require Merge Requests.
You should explore CI options - so tests are run when someone creates a Merge Request for ‘protected’ branches, like ‘main’.
Setting Up Runners#
ICHEC self-hosts our GitLab infrastructure. When you run a CI job it needs to run on a computer somewhere. When setting up a project you may need to request a ‘Runner’ from the Systems team.
First you can check if any ‘group runners’ are available to you - they may be depending on activity area.
Swap in ‘my_project’ in this URL https://git.ichec.ie/my_project/-/settings/ci_cd (it might be ‘my_group/my_project’) or go to Settings/CI/CD in the UI to see if any ‘group runners’ are available. If so you can use them.
If not you can make a ticket with Systems to discuss adding one.
Adding a Local Runner#
Even with a ‘group runner’ sometimes it is useful to run the CI on your own machine - it the group runner is overloaded, not set up yet or you want to troubleshoot without making lots of commits.
The official GitLab instructions are here: https://docs.GitLab.com/runner/install/osx.html If you have issues following them, some ‘it worked for me’ instructions are below:
Install GitLab Runner#
sudo curl --output /usr/local/bin/GitLab-runner "https://s3.dualstack.us-east-1.amazonaws.com/GitLab-runner-downloads/latest/binaries/GitLab-runner-darwin-arm64"
sudo chmod +x /usr/local/bin/GitLab-runner
su - <username>
cd ~
GitLab-runner install
GitLab-runner start
Register the Runner#
In the GitLab UI in the CI/CD Settings you can chose to ‘add a runner’. In that view you can choose ‘Mac’ and then give the runner a descriptive name like ‘MyName Mac’ or similar. Having your name is useful so someone can contact you if there are issues.
You will be given a command, e.g.:
GitLab-runner register --url https://git.ichec.ie --token xxxxxxxxxxx
you can run in a local shell to register the runner. You can pick ‘docker’ when prompted in the shell.
For the runner to pick up a job by default it will need to be given a ‘tag’ that is also given in the GitLab ci yaml for the project, e.g. something like ‘docker’
For the runner to run docker container jobs (probably what you want) you will need a docker or podman machine running on your Mac.