RepoBee is an opinionated tool for managing anything from a handful to thousands of GitHub repositories for higher education courses. It was created as the old teachers_pet tool was getting long in the tooth, and the new GitHub Classroom wasn’t quite what we wanted (we like our command line apps). RepoBee is heavily inspired by teachers_pet, but tries to both make for a more complete and streamlined experience.
Philosophy and goals¶
The primary goal of RepoBee is to lower the bar for incorporating Git and GitHub into higher education coursework, hopefully opening up the wonderful world of version control to teachers who may not be subject experts (and to their students). For new users, RepoBee provides both a tool and an opinionated workflow to adopt. For the more experienced user, there is also opportunity to customize RepoBee using its plugin system, which is planned to be expanded even more. RepoBee is primarily geared toward teachers looking to generate repos for their students. Many features are however highly useful to teaching assistants, such as the ability to clone repos in bulk and perform arbitrary tasks on them (tasks can be implemented as plugins, see Plugins for repobee).
Another key goal is to keep RepoBee simple to use and simple to maintain. RepoBee requires a minimal amount of static data to operate (such as a list of students, a URL to the GitHub instance and an access token to GitHub), which can all be provided in configuration files or on the command line, but it does not require any kind of backing database to keep track of repositories. That is because RepoBee itself does not keep track of anything, except possibly for the aforementioned static data if one chooses to keep it in configuration files. All of the complex state state is more or less implicitly stored on GitHub, and RepoBee locates student repositories based on strict naming conventions that are adhered to by all of its commands. This allows RepoBee to be simple to set up and use on multiple machines, which is crucial in a course where multiple teachers and TAs are managing the student repositories. There is also the fact that nothing need be installed server-side, as RepoBee only uses core GitHub features to do its work. For an experienced user, installing RepoBee and setting everything up for a new course can literally take minutes. For the novice, the RepoBee User Guide will hopefully prove sufficient to get started in not too much time.
Some terms occur frequently in RepoBee and are best defined up front. Some of the descriptions may not click entirely before reading the RepoBee User Guide section, so quickly browsing through these definitions and re-visiting them when needed is probably the best course of action.
- Target organization: The GitHub Organization related to the current course round.
- Master repository: Or master repo, is a template repository upon which student repositories are based.
- Master organization: The master organization is an optional organization to keep master repos in. The idea is to be able to have the master repos in this organization to avoid having to migrate them to the target organization for each course round. It is highly recommended to use a master organization if master repos are being worked on across course rounds.
- Student repository: Or student repo, refers to a copy of a master repo for some specific student or group of students.
- GitHub instance: A hosted GitHub service. This can be for example https://github.com or any Enterprise host.
The following conventions are fundamental to working with RepoBee.
- For each course and course round, use one target Organization.
- Any user of RepoBee has unrestricted access to the target organization (i.e. is an owner). If the user has limited access, some features may work, while others may not.
- Master repos should be available as private repos in one of three places: - The master organization (recommended if the master repos are being maintained and improved across course rounds). - The target organization. If you are doing a trial run or for some reason can’t have multiple organizations, this may be a good option. - Locally in the current working directory. If your master repos are trivial (e.g. empty), this may be a good option.
- Student repositories are copies of the default branches of the master
--single-branchcloning is used by default). That is, until students make modifications.
- Student repositories are named <username>-<master_repo_name> to guarantee unique repo names. - Student repositories belonging to groups of students are named <username-1>-<username-2>-…-<master-repo-name>.
- Each student is assigned to a team with the same name as the student’s username (or a concatenation of usernames for groups). It is the team that is granted access to the repositories, not the student’s actual user.
- Student teams have push access to the repositories, but not administrative access (i.e. students can’t delete their own repos).
Few of these conventions are actually enforced, and there are ways around almost every single one. However, with the exception of the one organization per course round convention, which must be ensured manually, RepoBee will automatically adhere to the other conventions. Although RepoBee does adhere to the conventions, there is no way to stop users from breaking them using e.g. the GitHub web interface, manually performing master repo migrations etc. Straying form the conventions may cause RepoBee to behave unexpectedly.
Usage with different platforms (GitHub, GitHub Enterprise and GitLab)¶
RepoBee was originally designed for use with GitHub Enterprise, but also works well with the public cloud service at https://github.com. Usage of RepoBee should be identical, but there are two differences between the two that one should be aware of.
As of v1.5.0, GitLab is partially supported. Please see RepoBee and GitLab for more information on which commands work, and how to use RepoBee with GitLab.
The Organization must have support for private repositories¶
Private repositories are key to keep students from being able to see each others’ work, and thereby avoid a few avenues for plagiarism.
- Enterprise: All Organizations on Enterprise support private repositories.
- github.com: You need a paid Organization (confusingly called a Team, but unrelated to the Teams inside an Organization). Educators and researchers can get such Organization accounts for free, see how to get the discount here.
- GitLab: All GitLab groups (self-hosted and on https://gitlab.com) support private repositories.
Students are added to the target Organization slightly differently¶
During setup, students are added to their respective Teams. Precisely how this happens differs slightly.
- Enterprise: Students are automatically added to their Teams in the Organization.
- github.com: Students are invited to the Organization and added to their Teams upon accepting.
- GitLab: Students are automatically added, both on self-hosted and https://gitlab.com.