Getting started (the show-config
, verify-settings
and setup
commands)¶
Important
This guide assumes that the user has access to a bash
shell, or is
tech-savvy enough to translate the instructions into some other shell
environment.
The basic workflow of Repomate is best described by example. In this section, I will walk you through how to set up an Organization with master and student repositories by showing every single step I would perform myself. The basic workflow can be summarized in the following steps:
- Create an organization (the target organization).
- Configure Repomate for the target organization.
- Verify settings.
- Migrate master repositories into the target organization.
- Create one copy of each master repo for each student.
There is more to Repomate, such as opening/closing issues, updating student repos and cloning repos in batches, but here we will just look at the bare minimum to get started. Now, let’s delve into these steps in greater detail.
Create an organization¶
This is an absolutely necessary pre-requisite for using Repomate.
Create an organization with an appropriate name on the GitHub instance you
intend to use. You can find the New organization
button by going to
Settings -> Organization
. I will call my target organization
repomate-demo
, so whenever you see that, substitute in the name of your
target organization.
Important
At KTH, we most often do not want our students to be able to see each
others’ repos. By default, however, members have read access to all
repos. To change this, go to the organization dashboard and find your way
to Settings -> Member privileges
. At the very bottom, there should be a
section called Default repository permission
. Set this to None
to
disallow students from viewing each others’ repos unless explicitly given
permission by an organization owner (e.g. you).
Configure Repomate for the target organization (show-config
and verify-settings
)¶
For the tool to work at all, it needs to be provided with an OAUTH2 token to
whichever GitHub instance you intend to use. See the GitHub OAUTH docs for
how to create a token. The token should have the repo
and admin:org
scopes. While we can set this token in an environment variable (see
Configuration), it’s more convenient to just put it in the configuration
file, as we will put other default values in there. We can use the
show-config
command to figure out where to put the config file.
$ repomate show-config
[ERROR] FileError: no config file found, expected location: /home/USERNAME/.config/repomate/config.cnf
show-config
will check that the configuration file exists and is
syntactically correct. Well, technically it will try to load the config and fail to do so if it
doesn’t exist or is incorrectly formatted and then display it to the user. Here,
the error message is telling use that it expected a config file at
/home/USERNAME/.config/repomate/config.cnf
, so let’s add one there. It
should look something like this:
[DEFAULTS]
github_base_url = https://some-enterprise-host/api/v3
user = slarse
org_name = repomate-demo
master_org_name = master-repos
token = SUPER_SECRET_TOKEN
Now, you need to substitute in some of your own values in place of mine.
- Enter the correct url for your GitHub instance. There are two options:
- If you are working with an enterprise instance, simply replace
some-enterprise-host
with the appropriate hostname. - If you are working with
github.com
, replace the whole url withhttps://api.github.com
.
- If you are working with an enterprise instance, simply replace
- Replace
slarse
with your GitHub username. - Replace
repomate-demo
with whatever you named your target organization. - Replace
SUPER_SECRET_TOKEN
with your OAUTH token. - Replace
master_org_name
with the name of the organization with your master repos. - It you keep the master repos in the target organization or locally, remove this option.
Important
The rest of this guide assumes the simplest possible setup of _not_ having
a separate master organization, but it is good practice to have the master
repos separate for the sake of maintainability. If the master organization
is configured in the config file, it won’t matter for any but the
migrate
command (which you don’t need then, anyway).
That’s it for configuration, and we can check that the file is correctly found
and parsed by running show-config
again:
$ repomate show-config
[INFO] found valid config file at /home/slarse/.config/repomate/config.cnf
[INFO]
----------------BEGIN CONFIG FILE-----------------
[DEFAULTS]
github_base_url = https://some-enterprise-host/api/v3
user = slarse
org_name = repomate-demo
master_org_name = master-repos
token = SUPER_SECRET_TOKEN
-----------------END CONFIG FILE------------------
Verify settings¶
Now that everything is set up, it’s time to verify all of the settings. Given
that you have a configuration file that looks something like the one above,
you can simply run the verify-settings
command without any options.
$ repomate verify-settings
[INFO] verifying settings ...
[INFO] trying to fetch user information ...
[INFO] SUCCESS: found user slarse, user exists and base url looks okay
[INFO] verifying oauth scopes ...
[INFO] SUCCESS: oauth scopes look okay
[INFO] trying to fetch organization ...
[INFO] SUCCESS: found organization test-tools
[INFO] verifying that user slarse is an owner of organization repomate-demo
[INFO] SUCCESS: user slarse is an owner of organization repomate-demo
[INFO] trying to fetch organization master-repos ...
[INFO] SUCCESS: found organization master-repos
[INFO] verifying that user slarse is an owner of organization master-repos
[INFO] SUCCESS: user slarse is an owner of organization master-repos
[INFO] GREAT SUCCESS: All settings check out!
If any of the checks fail, you should be provided with a semi-helpful error
message. When all checks pass and you get GREAT SUCCESS
, move on to the
next section!
Setting up master repos¶
How you do this will depend on where you want to have your master repos. I
recommend having a separate, persistent organization so that you can work on
repos across course rounds. If you already have a master organization with your
master repos set up somewhere, and master_org_name
is specified in the
config, you’re good to go. If you need to migrate repos into the target
organization (i.e. you are not using a master organization), see the
Migrate master repositories into the target (or master) organization (migrate command) section. For all commands but the migrate
command, the way
you set this up does not matter as Repomate commands go.
Setup student sepositories¶
Now that the master repos are set up, it’s time to create the student repos.
While student usernames can be specified on the command line, it’s often
convenient to have them written down in a file instead. Let’s pretend I have
three students with usernames spam
, ham
and eggs
. I’ll simply create
a file called students.txt
and type each username on a separate line.
spam
ham
eggs
An absolute file path to this file can be added to the config file with the
students_file
option (see Configuration file). Now, I want to create one student
repo for each student per master repo. The repo names will be on the form
<username>-<master-repo-name>
, guaranteeing their uniqueness. Each student
will also be added to a team (which bears the same name as the student’s user),
and it is the team that is allowed access to the student’s repos, and not the
student’s actual user. That all sounded fairly complex, but again, it’s as
simple as issuing a single command with Repomate.
$ repomate setup -mn master-repo-1 master-repo-2 -sf students.txt
[INFO] cloning into master repos ...
[INFO] cloning into file:///home/slarse/tmp/master-repo-1
[INFO] cloning into file:///home/slarse/tmp/master-repo-2
[INFO] created team eggs
[INFO] created team ham
[INFO] created team spam
[INFO] adding members eggs to team eggs
[WARNING] user eggs does not exist
[INFO] adding members ham to team ham
[INFO] adding members spam to team spam
[INFO] creating student repos ...
[INFO] created repomate-demo/eggs-master-repo-1
[INFO] created repomate-demo/ham-master-repo-1
[INFO] created repomate-demo/spam-master-repo-1
[INFO] created repomate-demo/eggs-master-repo-2
[INFO] created repomate-demo/ham-master-repo-2
[INFO] created repomate-demo/spam-master-repo-2
[INFO] pushing files to student repos ...
[INFO] pushing, attempt 1/3
[INFO] Pushed files to https://some-enterprise-host/repomate-demo/ham-master-repo-2 master
[INFO] Pushed files to https://some-enterprise-host/repomate-demo/ham-master-repo-1 master
[INFO] Pushed files to https://some-enterprise-host/repomate-demo/spam-master-repo-1 master
[INFO] Pushed files to https://some-enterprise-host/repomate-demo/eggs-master-repo-2 master
[INFO] Pushed files to https://some-enterprise-host/repomate-demo/eggs-master-repo-1 master
[INFO] Pushed files to https://some-enterprise-host/repomate-demo/spam-master-repo-2 master
Note that there was a [WARNING]
message for the username eggs
: the user
does not exist. At KTH, this is common, as many (sometimes most) first-time
students will not have created their GitHub accounts until sometime after the
course starts. These students will still have their repos created, but the
users need to be added to their teams at a later time (to do this, simply run
the setup
command again for these students, once they have created
accounts). This is one reason why we use teams for access privileges: it’s
easy to set everything up even when the students have yet to create their
accounts (given that their usernames are pre-determined).
And that’s it, the organization is primed and the students should have access to their repositories!