GitLab server

Users who wish to use the GIT source code version control system have two choices for a GIT server:

• Atlassian Bitbucket
• GitLab (Community Edition)

Only software projects that are available to the general public and that use an OSI-approved license and are allowed to use the Bitbucket system. All internal software, proprietary software or non-public software must use the GitLab server.

Logging in

	The GitLab server is located at https://gitlab.nrao.edu/ NRAO staff can click the "Openid Connect" button to log in with Microsoft SSO, or  enter their NRAO AD credentials on the "NRAO AD" tab. Do not use the "Standard" tab. Important: Access to NRAO GitLab is available from the public Internet. Any Public projects can be cloned and accessed by anybody on the Internet.
	If you do not have a WebAuthn / U2F token registered, enter the 6-digit code from your Authenticator app. Supported apps include Google Authenticator, Duo Mobile, Aegis Authenticator, Authy, etc.
	If you have a WebAuthn / U2F token registered, follow your browser's prompts and press the button/pad on your U2F token. If you need to log in without your token, click "Sign in via 2FA code" and follow the TOTP instructions above.

Navigating GitLab

The GitLab screen has several navigation elements at the top-left of the page. Most settings and preferences are accessed by clicking on your user icon in the top-right. The orange icon in the top-left returns to the main page. The "Search or go to" box will search for groups or projects. Below these are links to your Projects, Groups, Issues, etc.

SSH keys

In order to clone, push, or pull code, you will need to add an SSH key to your profile. If you have never generated an NRAO SSH key pair, see the page on SSH keys for information on creating an SSH key. Access your user settings from the avatar menu near the top-left and click on "Edit Profile".

Select the "SSH Keys" tab. Paste your SSH public key into the Key box and click "Add Key". Users are advised to use rsa (3072-bits) or ed25519 keys.

If you need to switch an existing repository from an HTTPS URL to a git URL, you can use the 'git remote' command to change the URL. It is not necessary to re-clone your project.

git remote set-url <SSH clone URL>

Updating SSH host keys

Occasionally it is necessary to generate new server host keys. When this happens, git and/or ssh will complain that the host keys have changed. To remove the outdated host keys, run the following command:

ssh-keygen -f "${HOME}/.ssh/known_hosts" -R "gitlab.nrao.edu"

Managing Two-Factor Authentication (2FA, MFA)

Two-factor authentication (also known as Multi-Factor Authentication or MFA) protects your account from unauthorized access by requiring an additional "factor" when logging in to GitLab. NRAO GitLab supports the use of hardware "U2F" keys as well as Authenticator apps ("TOTP" or "Google Authenticator"). Two-factor authentication can be configured inside the "Account" page of your user settings.

Click "Manage two-factor authentication" to choose your 2FA method. 

To enable a TOTP / Google Authenticator app, scan the QR code presented using the authenticator app, and enter the numeric code generated by the app into the "Pin code" field on GitLab.

To enable U2F authentication, you must have already have configured TOTP / Google authenticator. (This is a limitation of GitLab.) Insert your U2F device/key, scroll down to "Register a WebAuthn device" and click the "Set up new device" button. When prompted, press the button or touch the button/metal disc/pad on your U2F device and follow the prompts in your browser.

Generating Two-Factor Recovery Codes

If you have configured your SSH key access in GitLab, you can use that SSH key to generate new recovery codes to restore access to NRAO GitLab. You will be prompted to generate new recovery codes; answering "yes" will invalidate your existing recovery codes.

$ ssh gitlab@gitlab.nrao.edu 2fa_recovery_codes

***************************************************************************
 National Radio Astronomy Observatory computing facilities are exclusively
  for the use of authorized personnel, who are expected to abide by the
     terms of the NRAO Computing Security and Computing Use Policies.
***************************************************************************

Are you sure you want to generate new two-factor recovery codes?
Any existing recovery codes you saved will be invalidated. (yes/no)

Projects and Groups

GitLab support groups to enable multiple users to collaborate on private projects that only the group has access to.

Creating and managing Groups

All users can create groups inside GitLab. In order to keep groups organized, please make sure the name of any groups you create specifically reflects the purpose of the group. It is suggested to use either a project or department/division name as a prefix (i.e., vlass-ananlysis).

Note: Special characters, including underscores, are illegal in group names. Dashes may be used.

Enter the group name in the line next to "Group path". Be sure to enter a brief description of the group.

Choose a visibility level for the group. To project group projects and other details, select "Private". If you want your groups members and projects to be visible to all NRAO users, select "Internal". The "Public" setting allows viewing by anyone on the NRAO intranet, without authentication, and is discouraged. Click "Create group" to create your group.

After creating a group, you will be prompted to create a project inside that group.

Click the green "New Project" button to create a new project inside your new group.

Adding team members to your group

You can add other GitLab users to your group to allow a team to collaborate on a shared codebase. In order to add a user to your group, that user must have previously logged in to GitLab at least once.

Open the navigation menu and select Groups. Select the group you want to manage.

Select the Members tab.

In the top field, search for the user you want to add. Choose what level of access you wish to give to your group:

• Guest - Can create issues and view wiki pages
• Reporter - Read-only access to code, wiki,
• Developer - Read/write access to code, wiki, issues
• Master - Developer plus ability to create new projects
• Owner - Can add or remove group members

Click "Add to group" to add the member to your group.

Creating a project / repository

GIT repositories are contained in 'Projects' in GitLab. Users can create their own projects using the "New Project" button on the welcome page, or by clicking the grey + sign at the top-right. Most users will want to select "Create blank project".

On the next screen, enter a project name and select a namespace or group for the project. Please be descriptive in your project name - it will not need to be typed often. If your project should belong to your group and not specifically to you (i.e., departmental projects, project code, etc.), you can change the namespace of your project by pulling down the selector to the left of the Project name field and selecting the group name.

Choose a visibility level for your project. As with groups, "Private" projects are only visible to users and groups to which you grant access in the GitLab interface. "Internal" projects can be cloned (downloaded) by any NRAO staff who logs in. Public projects can be cloned without authentication by anybody on the Internet.

Note: If you have existing code that you want to push to Gitlab, YOU MUST UNCHECK "Initialize repository with a README" in order to create a blank project than can accept code pushes.

Once your project is created, the page for your project will be shown. This page contains the URLs for your project as well as instructions for cloning and/or pushing existing code to your project.

Copy the URL for use at the command line.

To clone the existing, empty, repository, find a place to store the new repo (it will be created in its own subdirectory), and run:

git clone gitlab@gitlab.nrao.edu:groupname/our-group-project.git
cd our-group-project
touch README.md
git add README.md
git commit -m "add README"
git push -u origin master

This will create an empty README.md file and push it to the server.

Migrating an existing GIT repository to GitLab

If you have been using GIT with another GIT server (GitHub, gitolite, Bitbucket, etc.), you can easily push your repo to a new project in GitLab. This is the process for migrating from the old gitdev.nrao.edu system:

1. Create the project in GitLab. MAKE SURE to uncheck "Initialize repository with a README"
2. Change to the working directory for your existing repo
3. Ensure your local copy is up to date by running 'git pull'
4. git remote add gitlab SSH_URL_FROM_PROJECT_PAGE
5. git push gitlab --all
6. git push gitlab --tags
7. git remote remove origin
8. git remote rename gitlab origin
9. git branch --set-upstream-to=origin/master master

Integration with NRAO Slack

NRAO Slack can be integrated with NRAO GitLab to allow slash commands from Slack and notifications from GitLab.

To add the NRAO GitLab App to your Slack channel

• Join the channel you wish to integrate with NRAO GitLab
• Verify that you can access the NRAO GitLab App by typing the slash command /gitlab help
• Mouse-over (hover your mouse over) the NRAO GitLab app icon and select "Add this app to a channel"

Allowing team members to commit to master

GIT uses branches to allow developers to operate in their own "sandbox" without affecting the main branch, "master". By default, GitLab protects the master branch so that only users with the "Master" permission can push code to it. To allow all team members with the "Developer" permission to commit/push to the master branch, navigate to your project and select "Protected Branches" from the settings menu on the right.

Change the "Allowed to merge" and "Allowed to push" settings to "Developers + Masters" and click "Unprotect"

More info on Protected Branches