Class setup instructions for GitLab

Access
GitLab @ UCSC

This page has instructions for setting up a class in GitLab. It assumes that you already have a GitLab account set up, and that you already are an owner of the class group. This setup need only be done once.

IMPORTANT NOTE: There are limits on the size of a single file in a repository, on the total repository size, and the number of files in a single repository. The default limits are 5MB, 80MB, and 2000, respectively. Limits are enforced when a repository is pushed to the GitLab server; if these limits are exceeded, the push will fail. Instructions on how to deal with this situation are available on the troubleshooting page.

If your class will need higher limits, please contact the GitLab admins to ask for higher limits.

Step 1: Make sure accounts are ready

You'll need to ensure that all of your course staff (TAs, readers, etc.) have accounts on GitLab. You can always add people later, but it's easiest if they have accounts before you start. Have them create their own GitLab accounts using their CruzID.

Step 2: create subgroup for current quarter

  1. Navigate to the Groups item in the menu in the upper left, and select it (1). Then, type the course name into the search box (2). Next, click on the class for which you want to create a new quarter (3). If the group for your class doesn't show up, it's likely that you aren't set as an owner for that class. Please email gitlab-admin«at»ucsc.edu to be added as an owner for your class groups on GitLab@UCSC.
  2. Select the Subgroups item (1) and click on the New Subgroup button (2).
  3. Fill in the fields on the form, as shown in the image below. Make sure you don't have spaces in the course abbreviation (e.g., fall17-01).
    1. Course quarter abbreviation. Make sure there are no spaces (e.g., winter19-01).
    2. More complete class quarter name.
    3. The description can be a few sentences helping students to figure out which class subgroup is which. For example, you might put the instructor name here if there are multiple sections.
    4. This should already be checked, but ensure that it is.
    When you've entered the information, click on Create group (5) in the lower left to set up the course group.
  4. You may want to disable notifications for this group. If you don't, you'll get an email every time a student commits, which could be annoying. We suggest disabling notifications by selecting Global (1) and then selecting Disabled, but you're welcome to pick any you want. You may change this at any time. Next, select Members (2) and click it to add course staff to the subgroup.
  5. Now, you need to add all of the course staff to the subgroup. These roles only apply to this particular subgroup, not to other subgroups of the same group. In other words, if you set this up for (say) your Fall 2017 TA staff, they won't have access to classes from other quarters unless you explicitly grant it.
    The two most useful are Maintainer and Reporter.
    • Maintainer: If you make anyone a Maintainer (or any role other than a Reporter), make sure the user really knows what they're doing with git and gitlab. A Maintainer can read and write any repository in the subgroup, and can add new projects. This is more dangerous, since a Maintainer can modify the state of student repositories by committing or doing other operations.
    • Reporter: This is the safest choice for most TAs and readers because users with this role can't alter student repositories on GitLab, and thus can't mess things up on the server. Reporters can read any repository in the subgroup (including cloning it to their local computer to test / grade it), and can make changes to their local copy (and even commit the changes!). However, they can't push their commits back to GitLab or make changes to a student repository using the GitLab GUI, so they can't accidentally modify or damage a student repository.
    Add each instructor, TA, and reader by typing their CruzID into box (1), selecting the desired role in box (2), setting an expiration date (if desired) in box (3), and clicking Add to group in box (4). IMPORTANT: do not add students to this group!

Step 3: set up class repositories

At this point, you're ready to create student repostories and set up access permissions for them. While you can do it manually, one student at a time, that's a slow, error-prone approach. Fortunately, GitLab has a great REST API that we can leverage to run a script that creates student repositories on GitLab @ UCSC. To do this, you'll need Python 3, the createrepos script and the Python Gitlab library. Follow these steps to install the script:

  1. Download the script (type this as a single line):
    curl -o createrepos.py 'https://gitlab.soe.ucsc.edu/gitlab/elm/gitlab-utils/raw/master/createrepos.py?inline=false'
  2. Install the latest version of the Python 3 Gitlab library:
    pip3 install --upgrade --user python-gitlab
  3. Make the script executable: chmod 755 createrepos.py

Using the script

The script is relatively straightforward: provide it with a personal access token (the token will need API access) generated by GitLab, and the name of your group (e.g., cmpe000/fall17). There are two ways to use the script.

The first way is appropriate if each student has their own repo. In this case, the repo will be named with the student's CruzID. The input file is a list of CruzIDs, one per line. Each CruzID may end with @ucsc.edu, but need not. Blank lines and lines starting with # are ignored. A sample command would be: createrepos.py --token 123456789abcdef --studentlist fall17-students.txt cmpe000/fall17

The second way is appropriate if multiple students will be sharing a single project repository. The command is similar (specifying import repo and token the same way), but the input list is now a sequence of lines, each of which specifies the repo name followed by one or more users who have access to the repo. If the repo doesn't yet exist, it's created. Users specified on the line get access to the repo; those not specified lose access to the repo. The contents of the repo remain unchanged, so you can always add a user back and run the command again. createrepos.py --token 123456789abcdef --repolist fall17-repos.txt cmpe000/fall17 Note the added argument --repolist.

Script arguments

By default, each student repository will be cloned from https://gitlab.soe.ucsc.edu/gitlab/classes/empty_repo. You may substitute a different repo for the clone source if you like, using the --import_repo repo argument. An example command is: createrepos.py --import_repo https://gitlab.soe.ucsc.edu/gitlab/classes/my_repo \
   --token 123456789abcdef --studentlist fall17-students.txt cmpe000/fall17
Obviously, the repo must be publicly available to serve as a clone source. As an instructor, you can create a repo in the classes project on GitLab @ UCSC that you make public and use as a template. We suggest naming the repo classes/cmpe000_template or something similar. Alternatively, you can create your repo in the classes/cmpe000/ project.

The default role for students is developer. This role allows students to commit changes to code, but not to modify permissions on repos. You may wish to allow students to give access to others to their repo; if so, use the --role maintainer option to the command. This is most useful if you're having students share repos (the second option above) and want them to manage their own access.

Rerunning the script

The script may be run as often as you like, and will create repositories that don't already exist. Already-created repositories are never altered by the script, though individual users may gain or lose access to a repo (for shared repos, never for individual repos). Only the second version of the command (using --repolist) will ever remove access; the first version will not.

Sample students file

# Sample list of students
#
elm
darrell

# Students who added late
elkaim

Sample repo list file

This repo list will create two repositories, group01 and group02. Each repo will be accessible by the users whose usernames are on the line following the repo name.

# Sample repo list

group01 elm darrell
# Second group
group02 elkaim sbsample

Running the script as a cron job

Since the script only creates repositories for students who've already got accounts, you're going to want to run the script regularly in the first week or so of classes. You can set it up as a cron job on one of the SOE servers (or on your own server). Please don't run the job more often than every hour because it causes load on the system by looking up each user in your roster, even if that user already has a repository.


Last modified 7 January 2019 by Ethan L. Miller (elm«at»ucsc·edu)