📚 gabe's wiki

GitHub Classroom (For TAs)

Mar 19, 202510 min read

I use GitHub Classroom to manage most assignments. This includes projects, writing and essays, homeworks, etc., but not exams.

Getting Set Up

If you are currently TAing one of my classes:

  • You should be a member of the g-simmons-classes organization on GitHub
  • You should have the “maintainer” role in a private repo named with the course code. For example, if you are TAing ECS170, you should see g-simmons-classes/ECS170 in the list of repositories you have access to on GitHub.

If there is an issue with one of these, let me know as soon as you can.

How do I create a classroom?

I’ll do this, TAs should expect to receive an invite link to the already-created classroom.

Notes to myself on classroom creation

This is apparently not possible from the CLI.

Go to https://classroom.github.com/classrooms and click “New Classroom” Put the classroom in the g-simmons-classes organization

Name the classroom with the following format:

g-simmons-classes-<course_code>-<term>-<year>

Where course_code is ECS188, ECS170, etc., <term> is ss1, ss2, fall, winter or spring, and year is the four-digit year e.g. 2024.

For example:

g-simmons-classes-ECS188-fall-2024

How do I add students to the classroom?

Adding the student roster

Canvas integration requires permisssions at the UC Davis administration level, I haven’t gotten around to this yet. For now, we can import the roster from a CSV or TXT file.

  1. Download the roster using these instructions:

https://teacherscollege.screenstepslive.com/a/1286286-download-a-student-roster-in-canvas

Home Page > New Analytics > Reports > Class Roster > Run Report > Run Report

  1. Get a list of student emails from the roster file.

If you are comfortable using Bash CLI, you can do:

cat roster\ 10-20-2024.csv | cut -d ',' -f 4 | tail -n +2 > emails.txt

Emails.txt should contain a list of uc davis emails, one per line, without a header.

If you are not comfortable in the CLI, you should be able to do something similar using Google Sheets or Excel.

  1. Add the students to GitHub Classroom

Once you have the list of students:

  1. Go to the Students tab in GitHub classroom.
  2. Click “Update Students”.
  3. Upload the file using the Upload a CSV or Text File button.

img

img

  1. Invite the students

Once the roster is added, we need to invite the students. Post a Canvas announcement using the following template:

Hi folks,

This quarter we will be using GitHub Classroom to submit some of the assignments.

Please do the following steps as soon as possible:

  1. Create an account on GitHub if you don’t already have one. If you don’t want to associate your personal GitHub account with your academic work, create a new account.
  2. Open this link and sign in with your GitHub account.
  3. Select your student identifier to associate it with your GitHub account

How do I create an assignment?

img

For a given academic term (quarter), each assignment has:

  • A template GitHub repository that persists across terms.
  • A starter code repo used for the current term. GitHub Classroom creates this automatically.
  • Student forks of the starter code repo where students submit their work for the current term.

Some setup could make it more convenient to move content around between these three levels.

  • Clone the template repo.
  • Make the starter code repo a downstream remote of the template repo.
git remote add downstream <starter-code-repo>
  • Push to downstream whenever the template code repo is edited. Automation for this is an open TODO.
# from the template repo:
git push origin fall2024
git push downstream fall2024
  • Students should make the starter code repo an upstream remote of their forks. There should be instructions for this in the student guide to GitHub classroom, a separate article on this site. If you look for this and cannot find it, please notify me.

To make a new assignment:

Creating a new template repo on GitHub

  • Check if a template repository already exists for the assignment in the g-simmons-classes organization.
    • If a template repo does not exist, create a template repo in the g-simmons-classes/ organization on GitHub.
      • If you are not a part of this organization already, please contact me. All current TAs should be organization members.
      • Name the repo <course_code>-assignment-name. Do not hyphenate the course code. Use hyphens instead of spaces in the assignment name. Lowercase the assignment name.
cd <local-class-folder>
mkdir ECS188-annotated-bibliography
cd ECS188-annotated-bibliography
gh repo create g-simmons-classes/<coursecode>-assignment-name --private
gh repo edit --template
# gh repo create g-simmons-classes/ECS188-annotated-bibliography --private # example
git remote add origin <remote-url>
git remote add origin https://github.com/g-simmons-classes/ECS188-annotated-bibliography.git # example

To make the repo a template, navigate to Settings > General > Template repository in the browser, or use gh repo edit --template in the CLI.

How do I modify an assignment?

  • Create a local folder to link to the template repo.
    • Use git init to make your local folder a git repo.
    • Use git remote add origin <template-repo-url> to link your local folder to the repo that was created on GitHub.
  • Add assignment content to the local folder.
  • git add and git commit your changes
  • git push to make the changes available on the remote template repository

Using a template repo to create an assignment

  • Make the Assignment on GitHub Classroom:

    • Go to the GitHub Classroom page for the class, and click the New Assignment button
    • Select the template repository for the assignment. If none exists, see “Creating a new template repo on Github” above.

  • DO grant students admin permissions on their repositories.

  • DO enable feedback pull requests.

New Assignment

New Assignment

How do students complete and submit their work?

Student copies of assignments are forks of the assignment template. Whatever content is in the student’s fork at the deadline time is their submission.

How do I get student submissions?

You can clone all student repos to a subfolder of the current directory using the following CLI command:

gh classroom clone student-repos

This command will ask you to interactively select a classroom and assignment, then put all student repos in a subfolder of the current directory, titled <assignment-name>-submissions.

Using GitHub Classroom for Student Grades

Requirements:

For every class using GitHub classroom, there should be an additional assignment called “Grades”. This should be an individual assignment, since students’ grades are confidential information. The assignment should be created with no deadline.

The starter code repo for this assignment should include a file grades.yaml that has every assignment for the class, its weight, the deadline, any deadline adjustments, etc. All information required to calculate a student final grade.

grades.yaml should be a protected path.

Students cannot be admins on the grades repo, since this would allow editing the grades.yaml file.

I need to create a test student for the class.

The starter code repo for this assignment should also include a file calculate_grade.py that reads the content of grade.yaml and prints the student’s course grade with an explanation for how it was calculated.

The most recent version of calculate_grade.py at the end of the quarter will be the script used to calculate students’ final grades.

System Diagram

The website content for ECS170 is a subrepo of my personal website, managed using git-subrepo.

TAs should be able to edit content for the course site directly, by modifying the content in the ECS170 repo.

Changes from g-simmons-classes/ECS170 are incorporated into the site once per hour. This update could happen more frequently if needed. If you think this would be beneficial, please let me know.

System Diagram

https://medium.com/hostspaceng/triggering-workflows-in-another-repository-with-github-actions-4f581f8e0ceb

https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28#repository-permissions-for-actions

https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#create-a-workflow-dispatch-event

The class website repos get a personal access token with “write” access in the Actions category. This is required to be able to call the.

POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches endpoint of the GitHub API, which triggers an action in the gabe-simmons-teaching-wiki repo.

Actions: Read and Write everything else: no access

gh repo create —private g-simmons-classes/ECS171-public-website/

In my wiki:

git-subrepo clone https://github.com/g-simmons-classes/ECS171-public-website.git ECS171

Subrepo ‘https://github.com/g-simmons-classes/ECS171-public-website.git’ (main) cloned into ‘content/Classes/ECS171’.

In the ECS171 repo:

git-subrepo clone https://github.com/g-simmons-classes/ECS171-public-website.git website

This feels safe enough to me.

Useful snippets

Open all student submissions in your favorite editor

ls **/bibliography.md | xargs cursor

Preview sources in bibtex files

ls **/refs.bib | xargs grep -H '@'

List of students who filled out the collaboration survey

 ls **/survey.md **/submission.md | xargs grep 'Your Name:' | cut -d ':' -f 3 | tr '<>' ' '

Why GitHub Classroom?

git, GitHub, and GitHub Classroom* can be operated using a CLI. This has major benefits:

  • Repeated actions can be scripted
  • Appropriate commands can be generated by LLM tools

*The GitHub Classroom CLI is incomplete. For example, as of Nov 2024, there is no “Create Assignment” command.

Why not GitHub Classroom?

I am starting to get the suspicion that GitHub Classroom specifically doesn’t do much. In other words it’s a thin layer on top of git+GitHub. If I can replace the essential functionality of GitHub Classroom with git+GitHub in a future term, I likely will. This will not happen in Fall 2024.

More notes

From what I can tell, GitHub Classroom:

  • Creates starter code repos automatically from template repos, including:
  • Selectively copying only the default branch
  • Squashing commits
  • Changing visibility settings
  • Renaming the repo
  • Manages invite links that allow students to accept assignments
  • When students click the invite link, a fork of the starter code repo is created in the GitHub organization associated with GitHub Classroom.
  • Convenience commands to clone all student repos locally via gh classroom clone student-repos
  • Protected paths in student repos
  • … probably more, this list is incomplete.

Some things about GitHub classroom that I don’t like:

  • If an assignment is initially created without starter code, and at least one student has accepted the assignment, I do not see an obvious way to go back and add starter code. Students can, however, still add a starter code repository as a remote by hand.
  • Deadlines are presented in UTC time. Importantly, a midnight deadline in Pacific Time gets listed as 6:59 UTC the following day. I imagine this might confuse students about the deadline date.
  • I have had intermittent issues with accepting assignments. I have not been able to pinpoint this to a specific cause.

Trouble with Assignment Acceptance

Students have reported issues accepting assignments in some cases. This appears to affect some students and not others.

Troubleshooting Notes Variables:

  • Is starter code repo set? (yes)

  • Individual or Group (individual)

  • Repository Visibility (private)

  • Are students admins on their own repository? (yes)

  • Was the default branch copied, or all branches? (default)

  • Were feedback pull requests created? (no)

  • Is the starter code repo public? (yes)

  • Is the default branch standard (main) or non-standard (fall2024)? (fall2024)

  • Has any other student accepted the assignment already?

  • Has any other student submitted the assignment already?

  • Has starter code been updated since assignment creation?

  • Has starter code been updated since the first student accepted the assignment?

Test results: Updates made directly to template repo:

| assignment link | update since assignment creation? | test-student-1 accepted successfully? | update since test-student-1 acceptance? | student-1-submit-before-student-2-accepts | test-student-2 accepted successfully? | | https://classroom.github.com/a/_F4BipaH | N | Y | N | N | Y | | https://classroom.github.com/a/qCCzZ9vP | Y | Y | N | N | Y | | https://classroom.github.com/a/wq2kqoYp | N | Y | Y | N | Y | | https://classroom.github.com/a/IU48HepZ | N | Y | N | Y | Y |

I suspect feedback pull requests as the cause of the problem, though disabling them for Thesis Draft 2 did not fix the problem. May need to ensure that they are not enabled to begin with.

Seems related: https://github.blog/changelog/2023-12-08-upcoming-changes-to-assignment-repositories-and-starter-code-in-github-classroom/ Also related: https://github.com/orgs/community/discussions/127455 A useful script for granting admin access: https://github.com/orgs/community/discussions/142408 More: https://github.com/orgs/community/discussions/137078 More: https://www.reddit.com/r/CSEducation/comments/13pqfm1/is_anyone_using_github_classrooms/