Using Git, GitHub, and GitHub Classroom for Courses

Suggestions for Instructors

Git, GitHub, and GitHub Classroom can work together when teaching Data Science or other software-intensive courses.

Resources

1 Getting Started

1.1 Ensure Your Computer has a Recent Version of Git

Git is a free and open source version control system for your code on your computer and working with others.

If you have a Mac, Git is installed as part of Xcode.
The latest version for Mac/Windows/Linux is 2.42.0 (as of August 2023).
To check your version, open a terminal window and enter git --version.
To download or update Git for Mac or Windows, go to Git Downloads
The site also has Documentation and links to the Pro Git Book and GitHub Git Cheat Sheet

1.2 GitHub

GitHub is a cloud-based platform for hosting and collaborating on Git repositories. - There is a free version you can use along with educational benefits.

1.2.1 Sign up for a Personal GitHub Account for classes

Go to https://github.com/, enter an email address and click on the Sign Up for GitHub button
On the next screen, confirm your email and click on Continue
Create a strong password and click on Continue
Enter the username you want to use for this account and click on Continue
Accept or decline email updates and and click on Continue
Solve the puzzle(s) to verify your account and and click on Create Account
GitHub will send an email to the email address you entered with a “launch code”. Enter this code and your account will be created and activated.

1.2.2 Get a Personal Access Token (PAT)

As of January 2021, GitHub requires a GitHub PAT to access repos via a script.

To get a GitHub PAT, go to Creating a Personal Access token and follow the instructions
You can use it when using a terminal window, RStudio projects, or for a bash script to download or update (pull) and push student assignments.
Select the scope for repo.
Save your tokens to your system credential manager, e.g. by using the R {keyring} package.
Upon first use, you may be asked to always allow access by other applications. Say yes.

1.3 Teaching Git and GitHub without GitHub Classroom

One can teach how to use Git and GitHub without using GitHub Classroom. As an example one can use the following approach for issuing assignments and receiving student work.

Require each student to create a personal GitHub account.
Issue assignments as usual, e.g., through a learning management system such as Canvas or Blackboard.
Have students complete their assignments on GitHub by creating an organization for the class.
Have the students create a repo for each assignment.
Have students either 1) provide you access by admitting you to the organization with access to all repos or, 2) submit zipped files of each repo they complete to you via the learning management system.

While this is feasible, it means the instructor is managing across multiple GitHub organizations which can be cumbersome and time consuming.

An alternative is to use GitHub Classroom, part of the GitHub Education capabilities. The rest of this document assumes you have Git working on your local computer and an active GitHub account (typically a personal account for educational purposes).

2 GitHub Classroom

GitHub Classroom is a companion capability for GitHub from GitHub Education.

GitHub Classroom works with GitHub to allow an instructor to distribute assignments to students and then it automatically creates student repos within a single organization.
GitHub Classroom leverages GitHub organizations to facilitate management of student assignments and repos for a Course.

2.1 GitHub Classroom Quick Start for Instructors

The Quickstart guide provides the steps to establish your account, get educator benefits and then set up the organizations and GitHub Classroom App.

To access the Quickstart, go to Help (under your account icon in the top right) and select Education and then select Quickstart

3 Create Two GitHub Organizations

3.1 Background

A GitHub account can create or join multiple GitHub organizations.

A GitHub organization is a GitHub structure with an owner/administrator who manages the organization.
An organization can have members with different roles/privileges, multiple teams with different privileges and many different repositories.
The owner/administrator controls which people/teams can access which repositories.

The GitHub Classroom App Quickstart focuses on creating a GitHub “Semester” organization. To manage courses over multiple semesters, it helps to create a second GitHub organization at the Course level.

The GitHub “Course” organization will hold all of the materials for the course and serve as the baseline for the course over multiple semesters. Students will not have access to this organization. This organization can support multiple instructors by creating a GitHub Team for Instructors and allowing access to the repos via the team.
A GitHub “Semester” organization holds the materials to be shared with the students for a single semester of the course and it also holds all the student assignment repos for that semester. Create a new “Semester” organization for each semester you hold the course.

To see all your GitHub organizations,

Click on the Octocat icon on the top left to go to your account home page.
The account icon and name has a down arrow on the right side.
Click on the arrow to see all your organizations and then you can select which organization you want to work with.

In summary, there will be three structures involved in using GitHub with GitHub Classroom:

The GitHub “Course” organization: This has all the current and historical baseline of course materials. No student access.
The GitHub “Semester” organization: This has only course materials to be shared with students for a given semester and all the student repos for that semester.
The GitHub Classroom “Classroom” which is Not a GitHub organization. It is a separate site where you set up template repos for each assignment and create a URL link for each assignment to distribute to students. This site is for instructor use only and is not used by students.

3.2 Create the GitHub “Course” Organization

Follow the instructions on creating an organization to create a new organization or select Create an organization on the left side of your account home page.

On the Pricing Page, select Join for Free on the left.
Enter a name for the “Course” organization, e.g., AU-DATA-413-613.
Enter your account contact email.
Select that the organization belongs to My Personal Account
Solve the puzzle to verify your account and select Next
No need to add people yet so click on Complete setup
Scroll to the bottom and click on Submit
Your “Course” organization is now created.

3.3 Create a GitHub “Semester” Organization for Each Instance of the Course

Create a new organization for each semester’s version of the course. You will connect each semester’s class organization to GitHub Classroom. This is the organization students will join to get lecture notes, access their assignment repos, and submit their work.

Go to your account Settings and select Organizations and click on New organization
Select Join for Free
Enter a semester-unique name for the “Semester” organization such as AU-DATA-413-613-21F that identifies the course and semester (and perhaps section if you have multiple sections).
Enter your email and My personal Account, and then verify your account.
Click on the Complete setup and scroll to the bottom and click on Submit
You now have a “Semester” organization to share information with your students and hold their repos.

3.4 Add a Students Team to the “Semester” Organization

Students automatically have access to their individual repos such as each assignment. If you create repos you want to share across all the students, e.g., lecture notes, the easy way to provide access to each student is to create a GitHub Team to which you can assign the repo. When you add students to the team later on, they will have access to the repo.

Go to the Semester Organization in GitHub.
Click on View Organization
Click on Teams in the menu bar and then click on New team (Green button)
Call it Students
You will add each student to the team as they join the organization.
After you create the Lectures_Class repo later on, you will add it to this Students team and authorize the team access to the repo.

4 Create a GitHub Classroom “Classroom” for the Semester

4.1 Request Teacher Benefits/Educator Discount for the “Semester” Organization

The first step is obtaining GitHub Educator discount which allows you to have multiple private repos for each student for free.
For details, see the Quickstart section on Applying for an educator discount.
Go to GitHub Education and, in the top right, click Benefits.
Scroll down and select Get teacher benefits.
- Fill out the information as per the instructions.
- Since AU Faculty IDs do not include an expiration date, this may require redacting an employment contract, exporting it as a .png, and uploading the .png.
- Another alternative is submitting a copy of the course schedule for the upcoming semester showing your courses.
These may still generate error messages. If so, contact the GitHub Education Support for help.
When complete, click on Process My Application.
Applications are typically approved right away but may take a few days.
You need to renew your application for benefits each year.

4.2 Use GitHub Classroom to Create a Classroom for the Semester

For details, go to the Quickstart section on Set up GitHub Classroom.
The GitHub Classroom connects with your current GitHub account.
Sign into GitHub Classroom and authorize access for the account where you created the GitHub Semester organization.

To create the GitHub Classroom “Classroom”:

Select Create Your first classroom or New Classroom
The screen should show your GitHub organizations. Select the GitHub “Semester” organization you created for the semester, e.g. ...-23F, not the Course organization.
I tend to shorten the name as it will be the prefix on each student repo.
Skip the next two steps on adding TAs and adding students via the LMS (AU Canvas is not yet configured for GitHub).
Your Github Classroom classroom is now established and you should be able to see it in GitHUb Classroom.
You cannot see it in GitHub as it is not a repo or organization per se.

5 Configure the GitHub Semester Organization

5.1 Use the Educational Benefit to Upgrade the GitHub Semester Organization

Once your educational benefit is approved (you will get an email from GitHub), apply to upgrade your GitHub “Semester” organization.
Go to Upgrade your organization.
Click on your GitHub “Semester” organization. Select it as a classroom and then Finish Upgrade.
You should get an email right away stating that it has been approved.

5.2 Add Students to the Semester Organization

Adding students directly from Canvas to GitHub Classroom is not configured yet by AU.

You do not need to add students right away. You could invite them individually via their AU emails but it is just as easy to wait until they have a GitHub personal account and have them join the organization via an assignment.

Follow the steps below on issuing assignments to create an assignment “hw_00” in GitHub Classroom and issue it to students.

As each student accepts the assignment, they will be added to the GitHub “Semester” organization as an outside observer.
You then invite them to join as “members” and at the same time invite them to the Students team so they can see the lecture notes.

5.3 Add a TA to the GitHub Semester Organization

The GitHub Classroom App’s Add a TA or Invite a TA has not worked well in the past.

Once you have a TA with a GitHub account you can try to add the TA.
First, go to GitHub and select the Semester organization.
Click on View Organization and select People from the menu.
Click on Invite member and add the TA as an owner of the Semester organization so they have admin privileges.
Go to the GitHub Classroom, select the semester’s Classroom, and select TAs and Admins to invite the TA to the semester’s classroom.

5.4 Add the TA to the Course Organization

If you want to share the assignments repo with the TA so they can see the solutions, go to the GitHub Course Organization.

Create a TA Team.
Invite the TA to that team
Grant the Team access to the Assignments repo so they can see the solutions.

This next section assumes one has successfully completed the actions in Setup and has established at least two organizations (Course and Semester) under your GitHub account and linked the Semester organization to a Classroom for the semester in GitHUb Classroom.

6 Directory Structure

The workflows that follow are based on a recommended local directory structure.

nb: I use Microsoft OneDrive to store all my files but the following structure should work just as well if the directories are only local to your computer.

Each course has in its own directory, e.g., /DATA-413-613/

6.1 Course Content Directories

Underneath the course directory, there are three directories of core content that persist across semesters as the current and historical baseline for the course.

/Assignments/
/Lectures/
/bib/

These directories are each their own Git repository (repo). Their upstream repo is in the GitHub Course organization. None of these files are distributed to or shared with students.

/Assignments/ contains all the .qmd and HTML files for homework, quizzes, and projects as well as any necessary data files.
/Lectures/ contains all the .qmd and HTML files for each subject as well as associated data.
/bib/ contains the .bib files used in the lecture notes or assignments

The /Assignments/ and /Lectures/ directories each have sub-directories for each assignment or lecture topic, e.g., /hw01/ or lecture_01/.

The homework and lecture directory often have sub-directories, e.g., /analysis/ and /data/.

Some assignments may have additional sub-directories, e.g., for different shiny apps.

The analysis folder contains the .qmd files with the complete lectures or assignments along with the rendered output files with and without solutions.

The .qmd files for assignments have a YAML parameter called solutions. The solutions parameter is a logical variable which is used within the code chunks to determine which chunks to evaluate and/or include in the output.

With solutions: false, the output for the assignment does not contain any solutions. This version is distributed to students.
Withsolutions: true, the output file is renamed to add “solutions” to the file name. This one is used by instructors and TAs.

I also use an \Admin directory. It contains the syllabus and grading information. There is no need to push grading information to GitHub and doing so may create an issue under FERPA.

6.2 Student Content Directories

Different directories contain information distributed to students.

/Lectures Class/ has the same sub-directory structure as the /Lectures/ folder (a folder for each topic). The lecture notes are copied to here each week as they are updated from the /Lectures/ directory. This directory is its own Git repo. However, it is linked to an upstream repo in the “Semester” organization, not the “Course” organization.
/zAssignment_repos/ has a similar sub-directory structure as the /Assignments/ directory however each sub-directory is its own GitHub repo.
- The contents do not include any solutions.
- These repos should each have an upstream repo in the Course or Semester organization.
- These will become “template” repos on GitHub.
- As they are updated for a given semester, the repos must wind up in the Semester organization (via fork or push) where GitHub Classroom can find them.
- Recommend setting the upstream as the Course organization and then forking to the Semester organization to avoid having to change the upstream repo each semester for each repo.
/zStudent_repos/ will have a sub-directory for each assignment which will contain all the student repos for that assignment.
- When a student accepts an assignment, GitHub Classroom creates their repo for that assignment in the Semester organization with a name that combines the assignment name and the student GitHub ID.
- Use the GitHub Command Line Interface to clone the assignments this this directory (see Section 8.2).

This next section assumes one has successfully completed the actions in Directory Structure. There should be two organizations (Course and Semester) in your GitHub account with corresponding local directories and repositories. The Semester organization should be linked to a corresponding semester classroom in GitHub Classroom.

nb These workflows refer to the Canvas Learning Management System (LMS). The workflows should be similar if using another LMS, e.g., Blackboard.

7 Workflows

The following workflows help manage a course using Git, GitHub, and GitHub Classroom:

Manage course content within and across semesters
Provide Lecture Notes to students
Issue individual assignments to students
Issue group assignments to students
Review/Grade student assignments
Prepare for a new semester

7.1 Manage Course Content

Lectures and Assignments can be updated in the local directories and pushed to the GitHub Course organization repositories after knitting.

Lectures and Assignments are each a single repo. If you update content in different folders (different topics/dates), you can commit and push all updates from different folders at once if you choose.

To adjust the assignments to be different for different semesters while keeping the originals, suggest saving the file with the semester on the end of the name, e.g., _23F.qmd.

7.1.1 Knitting Files Manually with Solution Parameters

Instead of creating two different files for assignments and solutions, recommending using a YAML solutions parameter for knitr code chunk options.

You can use the YAML solutions parameter to control the output or evaluation of code you can create the different versions manually.

Choose which version, solutions or non-solutions, to create by changing the solutions parameter in the YAML header.
Since the files will overwrite each other, recommend knitting the solutions version first with the parameter set to true and then renaming the .html file to include “_solutions.html”.
Then, change the parameter to false and knit the non-solutions version for sharing with students.

params:
  solutions: true # or false for no solutions.

You can create a set up chunk to set the defaults and then adjust for individual code chunks.

As an example:

7.1.2 Knitting Files Automatically

If you use the YAML solutions parameter to control the output or evaluation of code, you can create the different versions automatically using functions from the R package {rresutils}.

This is a small package available from GitHub at https://github.com/rressler/rresutils.
Use devtools::install_github(“rressler/rresutils”) to install on your local machine.

There are two sets of functions. One set is for Quarto documents and one set is for R Markdown documents.

Both sets will create two versions of the output documents, one with solutions and one without.

See the repo Readme for instructions.

7.3 Issue Individual Assignments to Students

7.3.1 Create the Assignment as its Own Local Repo

To issue an assignment, it must be in its own repo both locally and on GitHub once the assignment is finalized and knitted in the \Assignments\ directory (and pushed to the GitHub Course Assignments repo).
Create a folder for the assignment in the local /zAssignments_repos/ folder. Recommend starting the name with something like hw01_, hw02_, etc..
Copy the non-solutions assignment files and any data from the local Assignments folder into the new repo under the appropriate sub directories. Make sure the ..._solutions.xxx file is not included.
Recommend against copying the entire assignment folder. If you do, be sure to delete the _solutions.xxx file and the .R history file and the .qmd file.
Deleting the original .qmd file means the students have to recreate all of the instructions which can lead to inconsistent documents for grading.
Suggest copying and then editing the .qmd file to remove all the solutions code chunks and saving the file as hwXX_Starter.qmd. In the assignment instructions, tell the students to rename this file with the homework number and their name.
Once all files are in place, initialize the directory as its own Git repo.
You have a choice for where to push the repo on GitHub.
If you want to preserve the assignment over multiple semesters (recommended), create a corresponding repo under the GitHub Course organization and push to that organization.
- Once you have changed it to a template repo (next), fork it to the GitHub Semester organization.
If the assignment is only for the current semester, create a corresponding repo under the GitHub Semester organization and push to that organization.

7.3.2 Configure Each Assignment as a Template Repo

GitHub Classroom will need to make copies of the assignment repo so each assignment repo needs to be a “Template” repo.
Go to the individual assignment repo on GitHub (not the Assignments repo).
Select the Settings for the repo.
Check the box for Template Repository (right under the Repository Name). This is what allows GitHub classroom to make multiple copies of the repo, one for each student.
If the repo is in the Course organization, fork a copy to the Semester organization.

7.4 Create the Assignment in the GitHub Classroom Classroom

The repo now exists on GitHub in the Semester organization. The next step is to create the assignment in the GitHub Classroom semester Classroom so it can be distributed to students.

Go to GitHub Classroom and then to the Classroom for the course and semester.
Click on New Assignment.
Fill in the title using the appropriate prefix, e.g., hw01. The names must be unique across assignments. Recommend keeping them short as they are the prefix for each student’s repo.
Select Individual Assignment.
Ensure the repos are Private.
Do not grant admin access to students.
Click Continue.
Click on Select a repository and start to enter in the name of the individual assignment repo in the GitHub Semester organization. After a few letters it usually finds it for you.
Click Continue (Skip the online IDE).
Skip Autograding and select`Enable feedback pull requests” and then click Create Assignment.
The assignment has now been created and has a unique URL Link for students, but students cannot see it.

7.5 Issue the Assignment to Students

To issue the assignment to the students requires distributing the URL link created by GitHub Classroom to the students so they can “accept” the assignment.

If you are not using an LMS for the course, you could just copy the link and e-mail it to the students.
When each student clicks on the link, GitHub Classroom will create the student’s assignment repo (from the template you provided) in the Semester organization.
Only the student, the TA, and you will be able to see their repo.
Students should clone their repo to their local machine. As they complete the assignment they should commit and push to GitHub so you can see their work.

7.5.1 Using the Canvas LMS

If you are using an LMS for the course, instead of emailing the students the link, use the LMS to create an assignment to distribute the URL link created by GitHub Classroom.

Go to Canvas and create a new assignment.
Edit the assignment instructions and add an external link by copying and pasting the URL from GitHub Classroom into the Canvas assignment instructions.
In the assignment instructions, tell students to click on the link to accept the assignment.
Make the Canvas Submission Type to be Online and just Text Entry.
Include point values and rubrics etc., as desired.
Choose the date you want to assignment to be visible, and to be due. Save and publish.
If using Modules, add to the appropriate module, publish the assignment, and ensure the module is published.
Students will not see the link until the assignment (and module) is published and the date-time for visibility arrives.

Here is a sample set of Canvas Instructions:

To accept the assignment, click here (Links to an external site.).

Rename the starter file under the analysis directory as `hw_02_yourname.qmd` and use it for your solutions.   
1. Modify the "author" field in the YAML header.  
2. Stage and commit your .qmd and HTML files (no PDF files).   
3. **Push both .qmd and HTML files to GitHub**.   
- Make sure you have knitted to HTML prior to staging, committing, and pushing your final submission.  
4. **Commit each time you answer a part of question, e.g. 1.1**   
5. **Push to GitHub after each major question**, e.g., Scrabble and Civil War Battles   
- **Committing and Pushing are graded elements for this homework.**  
6. When complete, submit a response in Canvas that your assignment is complete on GitHub.

Once the assignment becomes visible and students click on the link, their repos will be created and they can clone the repo and start their assignment.

7.6 Issue Group Assignments to Students

Group assignments are issued in similar fashion as individual assignments.

You specify the name and criteria for the groups. GitHub Classroom then allows the students to create and name their own groups.

Go to the GitHub Classroom classroom and click New assignment.

Enter the name using a prefix, e.g, gp01_xxx .
Select Group Assignment.
Name the set of Teams, e.g., “Group Projects”.
Set the maximum number of team members and maximum number of teams.
Keep it Private and do not grant admin access.
Select a template repository from the Semester organization and continue as before to Create assignment.
Get the link and issue as a group assignment in Canvas.
You will need to create the Canvas Groups separately or use the Canvas functionality to allow students to select their groups.

As students click on the link GitHub will invite them to join an existing group or create a new group (if they don’t see their group.

If a new group, students will select the name for their group repo.
GitHub Classroom will create a repo for each group and a team for each group in the GitHub Semester organization.
Each group/team will have access to their repository.

8 Review/Grade Student Assignments

This section assumes one has successfully issued an assignment to students using GitHub and GitHub Classroom as described in Workflows.

8.1 Student Repos

When the students accept an assignment, a repo is created in the GitHUb Semester organization with the name you assigned to the assignment followed by -student_github_id.

Note: Students can be quite creative when choosing their GitHub ID so you will probably want to create a reference somewhere to map their IDs to their names, especially for large classes.

As soon as students do their first push you can start looking at their code. You can review it in GitHub or you can clone the student repos to your local machine.

If you checked the “Enable feedback pull request` when you created the assignment, you will also get a pull request for each student. This will allow you to link directly to their code like a normal pull request to provide feedback if they have questions. They

8.2 Github Command Line Interface

The GitHub Classroom Assistant as been discontinued in favor of the Command Line Interface (CLI).

See Take GitHub to the command line for information on CLI.
See Using GitHub Classroom with GitHub CLI for information on using CLI with GitHub Classroom.
To install the GitHub Classroom extension, run gh extension install github/gh-classroom.

Once the extension is installed you can clone all the students repo for an assignment into a new directory.

Navigate in the terminal window to the directory where you want the new directory, e.g., zStudent_repos. Note the directory is empty in the Files tab.

Terminal Pane working directory for `zStudent_repos`.

Enter the command gh classroom clone student-repos. This will return an interactive list of your available GitHub classrooms. Use the arrows to move down the list to select the classroom of interest.

CLI list of available classrooms. Navigate and choose the classroom of interest.

Once the classroom is selected, GitHub will return an interactive list of available assignments in the classroom. Use the arrows to move down the list to select the assignment of interest.

CLI list of available assignments in the selected classroom. Navigate and choose the assignment of interest.

Once you select the assignment, GitHub will create a new directory for the cloned repos and begin cloning each repo.

CLI creates a new directory with the name `assigment name-submissions`.

Once the cloning is complete you can navigate to the new directory to see the individual repos.

The new directory with the cloned student repos.

8.3 Grading an Assignment

I use a shared Excel workbook (on OneDrive) to facilitate grading with a Teachers Assistant.

Typically the TA has done an initial review of the repos without making any changes or comments. The TA enters their comments on the shared Excel Spreadsheet (OneDrive).

The spreadsheet has the rubric for each assignment and columns for grades and comments. The TA colors the Total squares yellow when they have completed with a student.

Once the TA is complete, use CLI to clone the repos to ensure you have the latest version.

Once the repos are updated, you can use the RStudio Files pane to go repo by repo to grade each student’s work.

You can use the pull request or create a new branch called instructor and then switch to the branch to run the code and make comments or troubleshooting changes. You can do it with RStudio or with the terminal with:

`branch instructor`
` branch switch instructor` 
`git push origin instructor` to create the branch on GitHub.

This way the students can see their original code and any changes or suggestions you make once this gets pushed.

I record my grades and summary comments in the Excel spreadsheet shared with the TA. This allows me to see all of the comments and grades across all of the students to review for consistency (since there are usually common errors).

8.4 After Grading is Complete

Once all grading is complete, I can copy the grades and comments into each student’s Canvas assignment.

9 A New Semester

This section assumes you have completed a semester of teaching a course per the previous workflows.

To prepare for a new instance of a course consider the following steps:

Check if your GitHub PAT needs to be updated
Create a new semester organization on GitHub along with the Team for students and TA.
Use GitHub Classroom to create a new classroom for the semester.
Upgrade both the organization and the classroom for the educational discount (may need to re validate your status with GitHub).
Change the upstream repo for the Lectures_Class repo to the new Classroom Organization.

10 References

Jacob Fiksel, Leah R. Jager, Johannna S. Hardin & Margaret A. Taub (2019) Using GitHub Classroom To Teach Statistics, Journal of Statistics Education, 27:2, 110-119, DOI: 10.1080/10691898.2019.1617089 DOI Link