Fundamentals

repomate is an opinionated tool for managing large amounts of GitHub repositories for higher education courses. It was created as a result of the old teachers_pet tool not fulfilling our every desire, as well as GitHub’s migration over to the browser based GitHub Classroom, which did not quite strike our fancy. repomate is essentially a newer (and hopefully better) version of teachers_pet, written in Python (which is commonly used at KTH) instead of Ruby (which is barely used at all).

Philosophy and Goals

The primary goal of repomate is to lower the entry level 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). As such, repomate is firmly seated in the convention over configuration camp, favoring highly opinionated workflows that are easy to get started with, rather than highly configurable ones. The target audience is primarily teachers seeking to incorporate git and GitHub into their courses, but lack the time or expertise to build their own automation system from scratch.

Note

Is there a difference between git and GitHub? Yes! git is the version control system, and GitHub is a company that hosts git servers on github.com, and provides enterprise software for hosting your own GitHub instances. The terms are often intermixed, but the distinction is important.

Terminology

Some terms occur frequently in repomate and are best defined up front. Some of the descriptions may not click entirely before reading the repomate 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.
  • Student repository: Or student repo, refers to a copy of a master repo for some specific student.
  • GitHub instance: A hosted GitHub service. This can be for example https://github.com or any Enterprise host.

Conventions

The following conventions are fundamental to working with repomate.

  • For each course and course round, use one Organization.
  • Any user of repomate has unrestricted access to the target organization (i.e. is an owner).
  • Master repositories should be available as private repositories in the target organization (using local repos on the current machine is also ok and generally works well).
  • Master repositories are added to the master_repos team.
  • Student repositories are copies of the default branches of the master repositories (i.e. --single-branch cloning is used by default). That is, until students make modifications.
  • Student repositories are named <username>-<master_repo_name> to guarantee unique repo names.
  • Each student is assigned to a team with the same name as the student’s username. 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).

Note

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, repomate will automatically adhere to the other conventions. Although repomate 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 repomate to behave unexpectedly.