sedrila use for instructors

1. Preparations

All commands assume a Bash shell. The sedrila tool assumes a Unix environment. Under Windows, use WSL. sedrila does not work natively in Windows.

1.1 Set up sedrila andgpg`

  • Install sedrila (on Debian/Ubuntu): sudo apt install pipx pipx install sedrila
  • Install gpg:
    On Debian/Ubuntu, do sudo apt install gnupg.
    For other platforms, see GnuPG downloads.
  • Add export GPG_TTY=$(tty) to your .bashrc (required for passphrase entry). For details, see authors.md section 3.0.
  • Generate key: gpg --full-generate-key
    Use the name and email that the students should get to see. Make sure, the key does not expire during the courses for which you intend to use it. The simplest approach is to generate a key that never expires.
  • List keys: gpg --list-keys
    Note down the key fingerprint of your public key. This is the 40-digit hex string shown next to your email address.
  • Export public key: gpg --armor --export <keyfingerprint>
  • Set a useful timeout (e.g. 12 hours) how long gpg-agent should keep the passphrase before you need to enter it again:
    https://superuser.com/questions/624343/keep-gnupg-credentials-cached-for-entire-user-session

1.2 Make entry in sedrila.yaml

  • Send the course organizer your instructor entry for your course's sedrila.yaml. See the instructors part of your course's equivalent of https://courseserver.example.org/path/course/course.json to see what such an entry looks like.
  • In that entry, gitaccount is your username in the git service used in the course and webaccount is your username on the webserver serving the course content. The beginning and end line markers for the pubkey are optional.

1.3 Set up your workstation

  • During your work as instructor of a sedrila course, you need a directory tree into which you will clone and checkout the git repositories of all participating students. If you work for several such courses, their student directories need to be kept separate. Therefore, create a single root-level directory called as you like (e.g. sedrila/) and create a per-course top-level directory within it; we suggest it be named after the month in which the course started (e.g. 2026-04/ for a course starting in April 2026).
  • When you call sedrila instructor, you need to be in one of these directories.
  • Extend your .bashrc (or rather .bash_profile, if you have one) to set the environment variable EDITOR to point to the text editor you want to use when sedrila starts one. Example: EDITOR=/usr/bin/emacs.

1.4 Initial cloning of the student repos

  • The SeDriLa needs to tell the students to create a git repo on some git server and provide read and push rights to each instructor named in the course.
  • When they do this, the git server will send you an email message with a link to the repo, typically also containing instructions how to clone the repo. DO NOT FOLLOW THOSE INSTRUCTIONS AS THEY STAND!
  • Instead, for use with sedrila, we need to clone the repos into a working directory that is named according to the students' git username (not the repo name as would be the default; those repos will mostly have similar names).
    So instead of git clone git@github.com:myaccount/mysedrilacourse.git
    do a git clone git@github.com:myaccount/mysedrilacourse.git myaccount
  • You need to perform these clone operations manually before you can work on those students' repos using sedrila.
    Suggestion: If you are using GitLab, when a student adds you to their repo, you will receive notification emails containing a string of the form studentname / reponame. Cloning becomes easy by copy/pasting this string onto your commandline as cloneedrilarepo studentname / reponame after you taught your shell this procedure: clonesedrilarepo() { gitserver=git@git.imp.fu-berlin.de # replace this with yours cmd="git clone $gitserver:$1/$3.git $1" echo $cmd $cmd }

2. instructor menu: Checking a submission

2.1 The very first time

Before you check your first submission for a given course, you need to import all instructors' public keys into your gpg so that sedrila can identify the "submission.yaml checked" commits of all instructors, not only yourself.

To do so, go to a student directory that contains a proper student.yaml file and call
sedrila student import-keys
This is the only time you will need to call sedrila student (as opposed to sedrila instructor).

If you do not have a student directory, create one yourself by git init mytmp; cd mytmp and then following the steps described in "Describing your course participation" in the sedrila user guide for students.

(On the next course, if the set of instructors is different, you can safely do the same routine again. gpg can cope with keys it already has imported previously.)

2.2 Regular use

To get a quick overview of a student's submission status without entering the interactive menu, use sedrila instructor status student1 (or with multiple directories).

Call sedrila instructor menu student1 or sedrila instructor menu student1 student2, where student1 and student2 are two students' git usernames and therefore also the names of directories in the course-level top directory in which the call needs to be made.
You can call sedrila with any number of directories theoretically, but the ideal case is two, where these students form a work pair and make corresponding submissions at the same time. Working with more than four directories at once is hardly practical.

When sedrila starts, it will git pull the repo and remove all entries from 'submission.yaml' that do not say "CHECK", unless you have worked on the so-created 'submission.yaml' already and not committed that work.

sedrila then provides a simple menu-driven command loop offering tools for marking submission items as accepted or rejected: - a webapp (used in the browser and usually the nicest choice) - calling your text editor for doing it manually - committing+pushing the result when you are done

Several assumptions about the SeDriLa in question are built into the webapp. In particular:

  • The underlying SeDriLa prescribes submission filenames and directory structure precisely, so that the directory trees can be merged naturally and corresponding files identified easily.
  • For many or most submission files, their basename (without the suffix) will be the name of the corresponding task, so that viewer can read submission.yaml and then identify (and mark) most of those files in the directory tree that are relevant for the current submission.

Based on this, the webapp presents a joint virtual filesystem formed by merging the contents of several students working directories, points out which students have submitted which tasks, and (at the file level) allows viewing pairwise differences between two students' exemplars of the same file.

2.3 Protocol checking

For tasks requiring command-line execution logs (.prot files), sedrila provides automated protocol comparison. Student protocols are checked against author protocols using @PROT_SPEC validation rules.

2.3.2 Webapp protocol checking

The instructor webapp automatically compares student and author protocols when viewing .prot files.

If encrypted protocol files (.prot.crypt) are present, the webapp will prompt for your GPG passphrase when starting (up to 3 attempts). The passphrase is verified and cached for the session duration. Passphrase prompts support local (file:// URLs) and remote HTTP(S) deployments.

Encrypted protocol files are created during the build process by encrypting each protocol file with the public GPG keys of all instructors listed in sedrila.yaml. This allows every instructor to decrypt the files using their own private key, enabling secure protocol access without additional key distribution.

Each command entry is color-coded:

  • Green (prot-ok-color): Passed automated checks
  • Red (prot-alert-color): Failed checks
  • Yellow (prot-manual-color): Requires manual review
  • Grey (prot-skip-color): Skipped entries

Failed entries show the specific mismatch (command or output) with the expected regex pattern. Manual entries display the author's instructions for what to check.

2.3.3 Validation rules

Comparison uses @PROT_SPEC blocks from author protocols (see authors.md section 2.3.2):

  • command_re=: Student command must match regex (fullmatch); if omitted, command check passes automatically
  • output_re=: Student output must contain regex match (search); if omitted, output check passes automatically
  • skip=1: Always passes, no manual review needed
  • manual=text: adds manual checking information for instructor (independent of automated checks); can be combined with regex checks

Entries without any spec default to manual review. Entries with command_re= and/or output_re= perform automated checks (green/red) even if manual= is present.

3. instructor status: Checking students' overall work status

sedrila instructor status in a student's workdir will show a summary table of worktime, accepted timevalue, and rejected timevalue. This is helpful for instance if students claim they have completed the course.

4. instructor book: Booking timevalue manually

In exceptional cases, instructors can add to or (more commonly) subtract from a student's current timevalue sum. Adding might be required if a student made an exceptional extracurricular contribution to the course. Subtracting might be required if a student broke the course mechanics (e.g. by force-pushing into their repo, thus breaking the instructors' histories) or cheated.

For instance, sedrila instructor book --timevalue=-1.0 somereason is how to start the subtraction of 1 hour; use positive values for adding. somereason must either be the name of a task or the name of a manual_bookings.types entry from sedrila.yaml (see authors docs).

Sedrila will start an editor for entering an explanation; make sure your $EDITOR environment variable is set to the editor you'd like to use. These data are then put into a signed, empty commit. The format of this commit will be recognized by sedrila's timevalue logic.