RepoBee is an opinionated tool for managing anything from a handful to thousands of Git repositories on the GitHub and GitLab platforms. There were two primary reasons for RepoBee’s inception. First, the old teachers_pet tool that we used previously lacked some functionality that we needed and had been archived in favor of the new GitHub Classroom. Second, GitHub Classroom did not support GitHub Enterprise at the time (and as of this writing, still does not, although efforts have been made to that end). RepoBee is heavily inspired by teachers_pet, as we enjoyed the overall workflow, but improves on the user experience.
Philosophy and goals¶
When RepoBee was first created, it’s goals were simple: facilitate creation and management of student repositories for courses at KTH, using GitHub Enterprise. Since then, the scope of the project has grown to incorporate many new features, including support for the GitLab platform. For new users of Git/GitHub/GitLab in education, RepoBee provides both a tool to make it happen, and an opinionated workflow to ease the transition. For the more experienced user, the plugin system can be used to extend or modify the behavior of RepoBee. While creating a plugin requires some rudimentary skills with Python programming, installing a plugin created by someone else is no harder than installing RepoBee itself. The plugin system enables RepoBee to both be easy to get up and running without any required customization, while still allowing for a degree of customization to those that want it. See Plugins for RepoBee for details.
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 platform instance and an access token to said platform), 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 the hosting platform, 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. RepoBee is very intentionally designed not to be a service, but an on-demand tool that is only in use when explicitly being used. This means that nothing needs to be installed server-side for RepoBee to function, which also happens to be key to supporting multiple hosting platforms. 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 within the hour.
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. As GitHub is the default platform, these concepts are based on and often refer to GitHub-specific terms. For a mapping to GitLab terms and concepts, please see the RepoBee and GitLab section.
- Platform: Or hosting platform, refers to services such as GitHub and GitLab.
- Platform instance: A specific instance of a hosting platform. For example, https://github.com is one instance, and an arbitrary GitLab Enterprise installation is another.
- 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.
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).
RepoBee has no way of enforcing these conventions, other than itself strictly adhering to them. For example, there are no countermeasures against someone manually changing the names of student repositories or their URLs, and as there are endless variations of things that can be manually changed, there are no safety checks against such things either. If you have a need to manually change something, do keep in mind that straying from RepoBee’s conventions may cause it to act 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.6.0, GitLab is supported by most features. 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.