repobee / repobee

CLI tool for managing Git repositories on GitHub and GitLab in the context of education

Overview

RepoBee is a command line tool that allows teachers and teaching assistants to work with large amounts of student Git repositories on the GitHub, GitLab and Gitea platforms (cloud and self-hosted). The archetypical use case is to automate creation of student repositories based on template repositories, that can contain for example instructions and skeleton code. Given any number of template repositories, creating a copy for each student or group is just one command away. RepoBee also has functionality for updating student repos, batch cloning of student repos, opening, closing and listing issues, no-blind and double-blind peer review, and much more!

In addition, RepoBee features a powerful plugin system that allows users to either use existing plugins, or write their own. Plugins can do a wide range of things, including making RepoBee compatible with multiple hosting platforms (GitHub, GitLab, Gitea), providing compatibility with repositories managed by GitHub Classroom, or running JUnit4 test classes on cloned student repositories.

Still not quite sure what RepoBee actually does? The demo video below briefly explains some of the most important concepts, and showcases how RepoBee can be used to setup and clone student repositories, as well as how to write a simple plugin.

repobee-demo-low-quality.mp4

Short video demonstration of using RepoBee and writing a simple plugin. For a higher-quality version of this demo, click this link!

Feature highlights

RepoBee has a lot going for it. Here are some of the things we are most proud of:

• Compatible with GitHub, GitLab and Gitea: No platform lock-in!
• Support for group assignments (multiple students per repository)
• No-blind and double-blind peer review, directly on the hosting platform
• Generate, clone and update student repositories based on templates
• Open, close and list issues
• Extend and customize RepoBee with the plugin system
• Very little configuration required on the Git service platform side
  • The only requirement is to have an Organization/Group with private repository capabilities!
• No local configuration required
  • Although setting a few defaults is highly recommended

For a full list of RepoBee's built-in (i.e. non-plugin) features, see the user guide and CLI reference.

Getting started

First, either install RepoBee or grab the Docker image. Then, start exploring the Docs, where you (among other things) will find the user guide. It covers use of RepoBee's various commands by way of practical example, and should set you on the right path with little effort.

We also provide a Gitea test instance for playing around around with RepoBee in an environment where messing up has no consequence. See the RepoBee Gitea docs for details on how to use RepoBee with Gitea.

Install

We provide an install script that sets up an isolated and correctly configured environment for RepoBee, granted that you have Python 3.9+ and Git installed. The script supports macOS, Linux and Windows Subsystem for Linux (WSL). You can execute it directly using curl, with either bash or zsh.

IMPORTANT: If you use any other shell than bash or zsh, you must still execute the install script with one of them.

$ bash <(curl -s https://repobee.org/install.sh)

$ zsh <(curl -s https://repobee.org/install.sh)

For additional details, please see the install docs.

Docker

We offer a fully featured Docker image that can be used instead of installing RepoBee.

Versioning

As of December 17th 2018, RepoBee's CLI is a stable release and adheres to Semantic Versioning 2.0.0. The internals of RepoBee do not adhere to this versioning, so using RepoBee as a library is not recommended.

The plugin system is mostly stable as of RepoBee 3.0, but there is a slight risk of breakage due to unforeseen problems. If you develop a plugin, please get in touch so that can be taken into consideration if breaking changes are introduced to the plugin system.

License

This software is licensed under the MIT License. See the LICENSE file for specifics.

Citing RepoBee in an academic context

If you want to reference RepoBee in a paper, please cite the following paper:

Simon Larsén and Richard Glassey. 2019. RepoBee: Developing Tool Support for Courses using Git/GitHub. In Proceedings of the 2019 ACM Conference on Innovation and Technology in Computer Science Education (ITiCSE '19). ACM, New York, NY, USA, 534-540. DOI: https://doi.org/10.1145/3304221.3319784

repobee's Issues

Handle timeout on push

If a push times out (see #27), it must be handled, as the "too many" is pretty arbitrary.

Add option to have local master repo

it would be easy to just check if there is a correctly named repo in the current directory. Should be explicit though, add --local option to CLI.

Too many concurrent pushes causes 504 errors

The KTH GitHub server starts timing out if too many pushes are made at the same time. The amount of concurrent pushes must be limited.

Refactor admin

create_student_repos can be removed, and create_multiple_student_repos should be split into several functions. And renamed.

Better config file/defaults

Right now, user isn't being set as it's not in the base parser.

Push repo

git_push(repo_path: str, remote: str = 'origin', branch: str = 'master')

Getting repos by name

Really doesn't work well for organizations with thousands of repos, it's just too slow.

Token ends up in the url in logs

Probably not the best idea. It's the GitError subclasses. Example of PushFailedError log output:

[ERROR] Failed to push to https://gits-15.sys.kth.se/test-tools/c-week-1
return code: 1
stderr: To https://gits-15.sys.kth.se/test-tools/c-week-1
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to 'https://slarse:<SUPERSECRETTOKEN>@gits-15.sys.kth.se/test-tools/c-week-1'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

The SUPERSECRETTOKEN shouldn't be there (that's not the actual output)

Decorator for type checking input values

Would be simple and useful. Could possibly take a dict of parameter name: type mappings

Migrate local repos into organization

Would be user friendly

Make it possible to create student repos from multiple templates in one command

Without having to redo the create teams/add to teams step over and over

Refactor test suites

The tests are a bit messy. Once all the tests are done, refactor everything.

Close issues

Given a list of students, master repo names and a regex pattern.

Windows support

There seems to mainly be issues with file encodings and temporary file access rights. Probably not too much work for someone who knows their way around Windows.

Migrate repos prints confusing logging info

Because it uses ensure_teams_and_members with empty member lists, it prints that it's adding nothing to the master_repos team.

Add basic CLI for easier manual testing

It's a bit of a bother to enter the interpreter over and over

Make repo creation async

Using this technique, one can push without setting remotes. Sooo, there is no need to wait for other pushes to finish.

Investigate if GitPython would be beneficial to use

Writing my own wrappers for now since I need so few of them, but if more advanced functionality is needed, GitPython may be an option. Big caveat is that Windows is only kind of supported.

Test the api_wrapper module

Not quite sure how to do it yet, but it needs to be done.

Add issue handling commands to CLI

Should be able to open/close

Additional commands that may be useful

• Add students to teams (e.g. only ensure_teams_and_members)
• Create repos only. This, however, requires teams, so except for a small performance impact, there is no practical difference between only creating repos, and ensuring teams/members and then creating repos. Then, it is essentially just setup_student_repos, but without pushing files.
• Clone student repos

Clean up the github_api and api_wrapper modules

It's getting a little bit messy. But better wait 'til after the core functionality is done, and then refactor for king and country.

Set up Travis

Validation errors result in error code 422

For example when trying to create a repo or team that already exists

Handle wrong base url, credentials and org name

And put out some nice logging so you know what went wrong

Refactor CLI

it's growing large and unwieldy

Migrate repo to organization

It would be nice to be able to migrate a repo from some arbitrary url to the organization

Update repos crashes if there are no student repos corresponding to the master repo

Log:

[INFO] cloning into master repos ...
[INFO] pushing files to student repos ...
[CRITICAL] Traceback (most recent call last):
  File "/home/slarse/.local/share/virtualenvs/gits_pet-jdPWeX1S/bin/gits_pet", line 6, in <module>
    exec(compile(open(__file__).read(), __file__, 'exec'))
  File "/home/slarse/Documents/github/cdate/gits_pet/bin/gits_pet", line 6, in <module>
    cli.main()
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/cli.py", line 249, in main
    args.org_name, args.github_base_url, issue)
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/admin.py", line 179, in update_student_repos
    failed_urls = git.push(push_tuples, user=user)
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/git.py", line 209, in push
    util.validate_non_empty(push_tuples=push_tuples, user=user)
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/util.py", line 17, in validate_non_empty
    raise ValueError("{} must not be empty".format(param_name))
ValueError: push_tuples must not be empty

Test on Windows

Once the CLI is finished, try to get Windows compatibility.

Handle update rejections

Currently, when update pushes are rejected, nothing happens but logging. There should be an option to open an issue in each repo to which pushes were rejected. At the very least.

Experiment with concurrency limit

The concurrency limit introduced in #27 is currently completely arbitrary (20). Should experiment a bit with it.

Create/Update repos crash if using -mn and master repo is not in organization

Log:

[CRITICAL] Traceback (most recent call last):
  File "/home/slarse/.local/share/virtualenvs/gits_pet-jdPWeX1S/bin/gits_pet", line 6, in <module>
    exec(compile(open(__file__).read(), __file__, 'exec'))
  File "/home/slarse/Documents/github/cdate/gits_pet/bin/gits_pet", line 6, in <module>
    cli.main()
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/cli.py", line 246, in main
    args.github_base_url)
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/admin.py", line 50, in create_multiple_student_repos
    github_api_base_url=github_api_base_url)
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/util.py", line 17, in validate_non_empty
    raise ValueError("{} must not be empty".format(param_name))
ValueError: master_repo_urls must not be empty

Improve testing of API classes

But first need to sort out the API, it's changing too rapidly to be worth testing at the moment #19

Opening/closing issues is too slow when there are thousands of repos

I thought making a single request for all repos and then filtering them would be faster in most cases, but when there are thousands of repos, it's really slow. This is a problem with pygithub and is isolated ot the PyGithubWrapper._get_repos_by_name function. One request per repo is slower when there are few total repos, but much faster when there are thousands of them.

Add more tests to admin

Both create_multiple_student_repos and update_student_repos need functional testing for more than just happy path. For example, update needs to be tested when there are students missing, when one or more master urls are incorrect etc. Same for create.

Update repos

Add a command to admin.py to update repos

Streamline CLI

The CLI is now fully featured, but it's a bit wonky right now. Some parsers inherit options form their parents that are unused (e.g. migrate-repos inherits student-list, which doesn't make sense). Because of the new migrate-repos command, there may also be a case for entirely getting rid of the option of using urls to designate master repos.

Create issues

Given a list of students, a list of master repo names and a .md issue file.

Create/update repos crash when using -mu and url can't be found

Log:

[INFO] cloning into master repos ...
[CRITICAL] Traceback (most recent call last):
  File "/home/slarse/.local/share/virtualenvs/gits_pet-jdPWeX1S/bin/gits_pet", line 6, in <module>
    exec(compile(open(__file__).read(), __file__, 'exec'))
  File "/home/slarse/Documents/github/cdate/gits_pet/bin/gits_pet", line 6, in <module>
    cli.main()
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/cli.py", line 249, in main
    args.org_name, args.github_base_url, issue)
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/admin.py", line 174, in update_student_repos
    git.clone(url)
  File "/home/slarse/Documents/github/cdate/gits_pet/gits_pet/git.py", line 131, in clone
    stderr)
gits_pet.git.CloneFailedError: Failed to clone https://gits-15.sys.kth.se/inda-17/week-55
return code: 128
stderr: Cloning into 'week-55'...
remote: Repository not found.
fatal: repository 'https://[email protected]/inda-17/week-55/' not found

Don't needlessly invoke the api to get master repo urls

For example, when cloning student repos, there's no reason to get the master repo urls.

Test on KTH Ubuntu computers

Same as #29 , #30

Create add student repos function

Has to do the following

• Pull master repo
• Set push remotes
• Push
• Remove master repo

signature: create_student_repos(master_repo_url: str, user: str, students: Iterable[str])

Add push remotes to repo

add_push_remotes(repo_path: str, remotes: List[str])

See https://stackoverflow.com/questions/14290113/git-pushing-code-to-two-remotes for adding remotes

Add cli command to verify connection

Refactor and test CLI

Split up parsing and handling of parsing, test the parsing and the handling.

Clone repo

Clone a repo into the current directory. Mainly for cloning master repo.

git_clone(repo_url: str, single_branch: bool = True, branch: str = None)

Options that should be available:

• single-branch (implies master, unless otherwise specified). Default is True.
• branch (implies single-branch, unless otherwise specified). Default is None.

travis updates to slack instead

emails are getting really annoying, fix later. https://docs.travis-ci.com/user/notifications/#Configuring-Slack-notifications

Clone repos command

Needs to be added to admin and cli

async cloning

When cloning batches, it's nice to do it asynchronously

Test on MacOSX

Same as #29