Using GitLab in the NHS England Secure Data Environment

GitLab is a code management and code version control tool available in the NHS England SDE. It provides users with a secure, cloud-based repository to store and back-up versions of code when using Databricks in SDE.

This guide is intended to help you get up and running using GitLab in SDE.

It provides guidance on:

• accessing GitLab in SDE
• integrating GitLab with Databricks Repository
• integrating GitLab with RStudio
• GitLab best practice

Please note GitLab is intended for code only. Users must not use GitLab to store any data or results.

Users are encouraged to use the extensive GitLab user guidance on the GitLab Docs webpage alongside this guide. 

For technical issues, including accessing the SDE, contact the National Service Desk on [email protected] or by phoning 0300 303 5035.

For general queries and data-related issues, contact [email protected].

SDE users are invited to attend regular drop-in sessions hosted by our data specialist team which are for questions and support related to using the SDE environment and GitLab.

Drop-in sessions occur every Monday, Wednesday and Friday from 10am to 11am GMT (excluding public holidays) via Microsoft Teams. Invites are sent with your SDE account activation email. Alternatively, contact [email protected] for more information.

When logging in for the first time, you will be asked to create a two-factor authentication code before you can sign in. Please refer to the SDE Set-up Guide for help setting up your two-factor authentication code and logging in to SDE.

To log in to GitLab from your virtual desktop:

1. Double click on the GitLab icon.

The Browser option screen will be displayed.

2. Select the browser you want to use.
3. Click OK.

The SDE Log In screen will be displayed.

4. Enter your email address and password.
5. Click Next.

The Two-factor Authentication Code screen will be displayed.

6. Enter your two-factor authentication code from your smartphone.
7. Click Log in.

The GitLab Projects screen will be displayed.

When logging in for the first time, a screen may be displayed requesting an ‘SSH key’.  This screen does not require any action and can be closed.

Each DSA has its own, dedicated GitLab project. Users on the same agreement can share code and content within GitLab, but sharing is prevented across agreements.

When first logging into GitLab, users will notice that the shared Project has been automatically created. The project name is identical to the agreement the user has selected.

Users cannot create new Projects within GitLab in SDE. Instead, users should create a folder structure within the Project, to organise their work.

Integrating GitLab with Databricks Repos will allow you to develop code in a Databricks notebook, synchronise code with a remote GitLab Repository (Repo) and use GitLab commands for updates.

To integrate Gitlab with Databricks you need to create a personal access token in GitLab and save it in Databricks.

Once you have set up your Databricks Repos you can run notebooks or access project files stored in a remote GitLab Repo.

You only need to follow this integration set up process once for each Databricks workspace you have access to.

For further information on how you can use Git functionality in Databricks Repos, please refer to Git Integration with Databricks Repos.

To create a personal access token and save it to Databricks, follow the steps on the Databricks site to configure Git credentials.

When selecting the specific scopes, you need to tick 'read_repository' and 'write_repository' to give you the correct permissions.

Databricks Repos provides repository-level integration with GitLab. Once you have integrated GitLab with Databricks Repos you can develop code in a databricks notebook, synchronise it with a GitLab project and use GitLab functionality for source control.

Please note that you will need to complete these steps for each GitLab project that you want to connect to your Databricks Workspace.

To clone a GitLab project:

1. In GitLab, navigate to the GitLab project that you wish to clone.
2. Click Clone.
3. Click the Copy URL button to the right of Clone with HTTPS.  

4. To clone the repo in Databricks, follow the steps on the Databricks site to clone a repo connected to a remote Git repository.

RStudio users can interact with GitLab directly from the RStudio console after establishing a connection. However, for certain purposes it may be more convenient to work directly from the GitLab tool.

To integrate Gitlab with RStudio you need to create a personal access token in GitLab and then clone a project.

Users need to complete a connection process the first time they use GitLab with RStudio. Once established, the setup process is not required for subsequent logins.

To create a personal access token in GitLab, follow the steps on the Databricks site to configure Git credentials.

To start working with code in RStudio you need to create a clone repository.

Cloning a repository is a convenient way of downloading all the code in an existing repository in GitLab to a folder in RStudio.

To clone a GitLab repository:

1. Open GitLab.
2. Click on Menu.
3. Select Projects and search for and click on the required project.

4. Click on Clone.
5. Click the Copy URL button to the right of Clone with HTTPS

You now need to clone the project in RStudio:

6. Open RStudio.
7. Select File.
8. Select New Project.
9. In the New Project Wizard, select Version Control.

10. Select Git.

11. Paste the HTTPS URL into the Repository URL field.
12. In the Create project as subdirectory of field, select the folder you want to create your project in.

13. Click Create Project.

The GitLab Sign in window will be displayed.

14. Enter your GitLab username in the first field.
Please refer to the Finding your GitLab username section for information on how to find your GitLab username.

15. Enter your GitLab personal access token in the second field.

16. Click Sign in.

Your cloned project will be displayed and is now available to work with in RStudio.

Agreement restrictions

Users can only move code between RStudio and GitLab when working under the same agreement.

Saving changes

RStudio does not automatically save changes, so it is important for users to save regularly using the Save button, including before committing to GitLab.

If the Git connection pane does not show in RStudio after creating a connection with GitLab, use the following steps to display the pane.

To display the Git connection pane:

1. Run the following script from the RStudio Terminal:
   git status
2. Copy, paste and run the last two lines of the output.

3. Reload the project by selecting the project from your home folder.

The Git pane will be displayed.

Committing changes is the process whereby changes to code in Rstudio are updated in the GitLab repository.

Users have 2 methods for committing changes to GitLab when using RStudio:

• typing commit commands into the Terminal - for help on commit commands, type help() into the RStudio console, which will bring up the Help tab, then search for commit
• using the Commit button within the Git tab - this opens a separate screen, where commits can be performed

Users are strongly encouraged to use commit commands, rather than the Commit button and Commit screen. This is because users can experience issues when navigating away from the RStudio Commit screen in SDE.  

To commit changes to GitLab from RStudio using the Commit button:

1. Select Git.
2. Select the project(s) you want to commit.
3. Select Commit.

The Rstudio Review Changes window will be displayed.

4. Enter a message, if required, in the Commit message pane.
5. Select Commit.

The Git Commit window will be displayed. You may need to paste your username and email into the Terminal as prompted.

To paste your credentials into the Terminal, close the Commit pane and navigate to the Terminal. Edit the Git config script with your personal details as pictured below and paste your credentials in. You may need to right click and select paste if CTRL+V doesn’t work in the Terminal.

You can now commit the changes and push them to GitLab.

6. Click Close.

You now need to push the changes through to GitLab.

7. Click the up arrow icon from the Git pane.

The Git Push screen will be displayed and the changes will now be committed.

To find your GitLab username:

1. In GitLab, click on the down arrow alongside your user profile icon.
2. Select Preferences from the drop-down menu

3. Select Account from the left-hand bar.

Your GitLab username can be found in the field to the right of the Change Username Path field.

Frequency of commits

Working practices within teams vary, as do the frequency with which users will commit their code to GitLab. As a guideline, users are encouraged to commit code in GitLab at least once a week.

Working together on code

When more than one user is working on the same code, users are advised to create their own branch to work within.

Even where two users are ‘pair-programming’ a particular section of code, it is recommended that they do so within separate branches. These branches should first be merged into a single branch, and subsequently merged into Master. Doing so will provide greater transparency of any conflicts or errors.

To keep your branch up to date with Master, you can use GitLab’s Merge Request functionality. Rather than having Master as the target branch, simply set it as the source branch, and set your user branch as the target branch. Doing this should achieve the same result as performing a ‘pull’ from Master and should help to avoid merge conflicts.

Handling merge conflicts

For detailed guidance on handling merge conflicts, please refer to the Merge conflicts section of GitLab Docs support pages.

Various resolution approaches can apply when handling merge conflicts, depending on the details of the conflict. Less experienced users are encouraged to consult with expert users for direction.

Reverting to a previous version of code

For detailed guidance on reverting to a previous version of code, please refer to the Revert changes section of GitLab Docs support pages.