GitLab is a Git-based repository management system that provides a platform for software development collaboration, issue tracking, a project-based wiki area and code review features through a intuitive web based interface.
Athena GitLab Project
The GitLab project page for the ATLAS offline software repository is a single portal for every commit, branch, tag and merge request in all the ATLAS offline release and development branches. Although there are other repositories associated with ATLAS software development review shifters will only need to track code contributed to the main repository (Athena).
This tutorial does not cover the use of the git client and the associated workflow used for managing ATLAS software. Please refer the Git tutorial for further information.
GitLab authentication is provided by CERN SSO so as a member of ATLAS it is assumed that you will have access by default. If you have access then the main project page should look like the following:
There are specific per-project privilege levels in GitLab (e.g. guest, reporter, developer, owner) which provide adequate protection from unwarranted changes. At present you will need the developer role in order to contribute to merge requests which is set by default.
Merge Request Activity
All merge requests in the ATLAS offline code are handled through the gitlab interface. The current list of open merge requests can be found on this page:
The format of merge requests will be covered in detail in the Examples section and will be the main focus of your interaction with GitLab as a shifter. You will check that you are able to contribute to merge requests at the end of this section.
The volume of merge request activity is still relatively low - typically 50 or so are active at present - but this is expected to increase with time as more development groups within ATLAS use this workflow. It is therefore useful to filter open merge requests to match your assigned role on shift.
In the screenshot above open merge requests have been filtered to contain only requests with labels review-pending-level-1 and sorted by oldest updated. This gives an ordered list of merge requests to tackle when starting on Level 1 shifts. Similarly you may want to also for filter for merge requests with an urgent label.
Alternatively you can view an continuous stream of the project activity on this page with most recent updated first.
Repository Viewing
For more involved code reviews it may be necessary to inspect code that was not be directly modified as part of the merge request to get a greater understanding of the requested change. You can either clone the Athena repository by the following the instructions in the git tutorial or browse files from any branch or commit point directly through the gitlab interface.
As a simple example lets say you were interested in exploring the contents of files recently changed by commits as part of some doxygen maintenance work. There are a number of accessible views within gitlab to get this information. We could first perform a text search by commit message:
To get to the this page click through the menu and sub-menus highlighted at the top of the screenshot above and type the keyword (doxygen in this case) into the search field. By selecting one of the listed commits we can see the list of files changed by this commit with either an inline or side-by-side diff:
Clicking on view file for one of the 20 changed files displays the full contents at that point in the commit history:
On this page it also possible to view the file contents as it appears on other branches (e.g 21.0, 24.0, main) by selecting the highlighted menu preceding the file path. By clicking on blame you can also get provenance information on each line of code:
Profile Settings
To inspect and modify your profile settings click on the icon on the top right hand corner:
In the profile menu you can make the following changes:
- Change the email address, add an Avatar and supply supplementary contact information
- Modify the notification settings per project
- Add an ssh key for repository connections
Other GitLab Functionality
There are many other views and functionality available within GitLab which is not covered here due to their limited use with the Athena project:
- Issue tracker: The CERN Jira is favoured over the in-built GitLab issue tracker. Selecting the issue tracker in the GitLab Athena project will re-direct to Jira.
- Pipelines/builds: As described in the next section, we use the Jenkins platform for continuous integration.
Further Information
For further information on the GitLab service provided by CERN please refer to the CERN Git service page and this CERN GitLab Knowledge base article.