| Table of Contents |
|---|
Setting Up SDC with GitLab Repositories
The following sections provide instructions for SDC users on setting up GitLab repositories for
committing and sharing their code and any other documents.
GitLab provides an organizational structure of users and repositories managed respectively via
“groups” and “projects” to promote collaboration among teams of SDC users. Groups contain
members with different access levels to their project repositories based on the assigned roles:
Role | Read-Only | Read/Write |
|---|---|---|
Guest |
| |
Reporter |
| |
Developer |
| |
Maintainer |
|
GitLab Features:
Share code with specific team members, your entire team, or different research teams that are also using the SDC.
Simplified collaboration with shared read/write access.
Manage multiple repositories that are organized and structured in a logical manner.
Version control and source code management including:
File locking to help prevent conflicts
Users can work from their local copy of the code
Users can branch code to make changes and then quickly merge it after approval
🚪 Log In to GitLab
Within your SDC workstation, open a web browser, then navigate to https://gitlab.prod.sdc.dot.gov (be sure to include the “https://”). This is the URL to the SDC’s internal GitLab.
In the Sign in page, the LDAP login option is selected by default. Enter your SDC credentials as the LDAP username and password, then click Sign in.
The Welcome to GitLab web page is displayed.
Navigating to “Explore Groups” will allow you see all the public groups and projects.
Create a Group
In the Welcome to GitLab web page, select Create a group.
The New group form appears. Enter the name for the new group.
Select the Private option under Visibility level to only allow members in the group to see the group and its projects.
Select Create group.
A success message appears indicating that the group was created. You are now ready to add members to the group.
Add Group Members
Users assigned with the “Developer” or “Maintainer” role can add other GitLab members in the
SDC to their groups.
NOTE: SDC users are listed as a GitLab member in the Members panel only after they have
logged into GitLab. If you do not see your SDC colleague listed, please ask them to log in to
GitLab.
In the newly created project web page, click Members from the left navigation menu.
In the “Search for members” text box, start entering the name of the SDC user you want to add; then select the member’s name from the autocomplete list.
Select a role from the next drop-down menu. You can select the “Read more” link to view a comprehensive list of the different available permission levels and their access rights. A summary of the roles’ access types is also shown in Table 1 at the beginning of this chapter.
Select Add to group.
Create a Project
Select the GitLab icon on the upper left to return to the home page.
Select Create a project.
The New project form appears. Enter a name for the project.
Select the Private option under Visibility level, so that the project is only visible to users who are granted explicit access to the project.
Select the Initialize repository with README checkbox to automatically generate a readme file that contains the project’s repository details.
Select Create project.
A success message appears indicating that the project repository was created. You are
now ready to add members to the project.
Add Members or Groups to a Project
Select the GitLab icon on the upper left to return to the home page.
A list of your projects appears. Select the name of the project you want to add members
/groups to.
Click on Settings and then Members from the left navigation menu.
You can add individual users or entire groups to the project.
Select the Invite member tab to add members individually to the project.
Start entering the project member’s name or email address into GitLab
member or Email address to select from the autocomplete list.Select a role for the project member from the drop-down menu under Choose a role permission.
Click Add to project.
Select the Invite group tab to add an entire group to the project.
Start entering the group’s name into Select a group to invite to select from
the autocomplete list.Select a role to apply for the group from the drop-down menu under Max
access level.Select Invite to grant the group access to the project repository.
...
🔑 Generate SSH Key
To set up git Git integration, you need to have an SSH key on your SDC workstation. This key
authenticates your identification to GitLab so that you can push commits to the project
repository.
...
Your key authentication credentials
...
are, by default, stored in a hidden folder
...
| Code Block |
|---|
ls –a |
...
named “.ssh.”
...
Confirm this works by entering ls –a to see all objects in the current directory. You should see the .ssh listed:
| Code Block |
|---|
ls –a |
...
Generate a new key to store in this location by typing the following command and then hitting the Enter key:
...
You’ll need to ensure this folder exists in your home directory before creating your key.
This can be done using CMD Prompt.Open the CMD Prompt application as shown in the picture below.
b. The CMD Prompt opens and should be active within your home directory.
The title bar of the terminal window will display MINGW64/c/Users/<your-SDC-username>,
where <your-SDC-username> is your actual SDC user credential.
c. Use CMD Prompt to check if the .ssh folder already exists in your home directory:
At the prompt, type the following command and then hit enter.Code Block dir
d. Confirm whether you see the .ssh folder listed in the results:
e. If not found, then create the .ssh folder:
At the prompt, type the following and then hit enter.Code Block mkdir .ssh
...
f. Confirm the .ssh folder is now created:
At the prompt, type the following and then hit enter.Code Block dir
Next, use CMD Prompt to generate a new SSH key and store it in the .ssh folder.
a. Generate the key pair:
At the prompt, type the following command* and then hit enterCode Block ssh-keygen -t rsa -b 4096 -C "<your-SDC-username@dot.gov>"
*NOTE: Be sure to replace <your-SDC-username@dot.gov> with your SDC email address,
or other email address/ identifier of your choosing.
b. It will output the following message:
...
“Generating public/private rsa key pair.”
c. It will then ask you where to save the file
...
with the
...
prompt “Enter file in which to save the key:”
At the prompt, type the following and hit enter.Code Block C:\Users\<your-SDC-username>\.ssh\id_rsa
d. It will also ask you to enter a passphrase with the following 2 prompts.
• “Enter passphrase (empty for no passphrase):”
• “Enter same passphrase again:”
...
Hit the Enter key each time (no need to enter anything else) to accept the defaults.
e. The following messages confirm the new SSH key is now stored in the .ssh
...
folder.
• “Your identification has been saved in
...
C:\Users\<SDCusername>\.ssh
...
\id_rsa.”
• “Your public key has been saved in
...
C:\Users\<SDCusername>\.ssh
...
\id_rsa.pub.”
...
NOTE: Your SSH key pair is comprised of two files, which have been saved under the .ssh folder
...
in your home directory ( C:/Users/
...
<your-SDC-username>/.ssh/
...
) .
The private identification is saved in the id_rsa file and the public part of the key is saved in the id_rsa.pub file.
3. You now need to provide the
...
‘public’ part of this key to GitLab
...
:
In the CMD Prompt terminal, type the following command at the prompt, and then hit enter.
| Code Block |
|---|
cat ~/.ssh/id_rsa.pub | clip |
...
This copies the content of id_rsa.pub to your clipboard.
4. Next, open GitLab, and on the GitLab home page, you’ll add your public SSH key to your GitLab account:
a. In the upper-right corner, click on your avatar image and then click Settings.
...
b. From the left navigation menu, click SSH Keys.
...
c. In the Key field, paste your public SSH key.
...
d. The Title field will be automatically populated with
...
the email/identifier that you provided in step 2a.
eg. your-sdc-username@dot.gov (see image below)
e. Click the
...
‘Add key’ button.
...
f. GitLab will return a summary of your new SSH Key.
...
5. To test whether your SSH key was added correctly,
...
type the following command, in your
...
CMD Prompt terminal,
and then hit enter:
| Code Block |
|---|
ssh -T |
...
git@gitlab.prod.sdc.dot.gov |
a. The first time you connect to GitLab via SSH, you will be asked to verify the authenticity
of the GitLab host you are connecting to. Type “yes” to add the SDC internal GitLab to
the list of trusted hosts.
b. You should see the “Welcome to GitLab,
...
@SDCusername!” message.
NOTE: Once added to the list of known hosts, you will not be asked to validate the
authenticity of SDC internal GitLab’s host again. Run the above command once more,
and you should only receive a “Welcome to GitLab,
...
@SDCusername!” message.
c. If the Welcome message does not appear,
...
rerun the last commandin ‘verbose'
mode by replacing -T with -vvvT. This will return more details that can be used to help debug the
error
...
.
| Code Block |
|---|
ssh -vvvT |
...
git@gitlab.prod.sdc.dot.gov |
⏬ Clone a Repository
Now that you have a working ssh key, you can clone a repository to your workstation.
In your browser in SDC, go to https://gitlab.prod.sdc.dot.gov and navigate to the repository you wish to clone.
Clone > Clone with SSH > Copy URL
Back in the Git Bash application, first `cd ~/` to make sure you are in your home directory. Then type `git clone`, then right click and paste in what you copied from GitLab:
You now have the repository cloned to C:\Users\{yourusername}\{repository}
As always, git pull when you start up your workstation. Do work, then git push at least once at the end of your day. The GitLab service is backed up, and you should treat anything on your Windows workstation just like you would on a C:\ drive on laptop.
🤔 Git commands to remember
For working off the master branch, do this before starting work (after you log on to SDC, open up Git Bash and run these):
| Code Block |
|---|
git status
git pull |
For working off the master branch, do this any time you want to push.
| Code Block |
|---|
git status
git pull |
Optional, if you started a new script or want to add any other new files to the repo:
| Code Block |
|---|
git add . |
Optional, if you want to add one specific file to the repo:
| Code Block |
|---|
git add <type the file name> |
Use `-am` option in git commit to add any changes and type a short message about the commit in one step
| Code Block |
|---|
git commit -am '<type some message here>' |
| Code Block |
|---|
git push |