Git server

%TOC%

---++ RUG Git server

This describes how to create repositories on the git server of the RUG and enable other people to access them over the internet.

Familiarity is assumed with Git and SSH.

---+++ Repository directory

Staff members can get a directory in which they can create repositories.

To get an account with a repository directory, please provide us with:

• Your e-mail address*For accounts that can create repositories, *@rug.nl* addresses are required.

• Your SSH public key*This is a small text file (~ 1kb). If you use OpenSSH, it is by default *~/.ssh/id_rsa.pub*. Getting an SSH public key is outside the scope of this manual.

• Directory name*This will become part of the URL to your repositories. An obvious name could be the acronym of your department, project, or just your initials.

---+++ Checking access

Run this command to check your access to the server:

<verbatim> ssh git@vcs.service.rug.nl info </verbatim>

Anybody whose SSH public key was registered with the server can run this command. If successful, it lists the repositories you have access to, and your permissions to them.

Example output:

<verbatim> C abc/..* R W one/example R doc </verbatim>

Which means:

  * You can create repositories inside the directory *abc*.
  * You can read and write to a repository called *one/example*.
  * You can read the repository *doc*.

---+++ Creating a repository

To create a new repository, just clone from the directory where you have permissions to create repositories. Repositories that do not exist yet, will be created on the fly:

<verbatim> git clone git@vcs.service.rug.nl:abc/example </verbatim>

Breakdown of the URL:

"git"The username for SSH. This is always "git".

"vcs.service.rug.nl"DNS name of the Version Control Server. This is always "vcs.service.rug.nl".

"abc"This is the directory where you can create repositories.

"example"Name of the (new) repository.

When you create a repository, you will be registered as the owner of it. This enables you to grant access permissions to other persons.

---+++ Granting access to others

To enable third party persons to access the server, please provide their:

  * E-mail address
  * SSH public key

At this moment new accounts will need to be registered on the server manually by the server admins. In the future a web application may automate this.

Once they're registered, you can grant them access to repositories you own (or are allowed to administrate) by assigning *roles* to their e-mail address.

E.g. to enable John Doe to write to your repository *abc/example*, run the *perms* command using SSH like this:

<verbatim> ssh git@vcs.service.rug.nl perms abc/example + WRITERS john.doe@somehere.net </verbatim>

In this command, "WRITERS" is called a *role*. If you would want to grant John Doe only read access to the repository, you could specify "READERS" instead.

To *revoke* a role instead, replace the '+' in the command with a '-':

<verbatim> ssh git@vcs.service.rug.nl perms abc/example - WRITERS john.doe@somehere.net </verbatim>

---++++ Roles

There are more levels of access than just "READERS" and "WRITERS". Here is the entire list of roles with their permissions:

• READERS*Only reading is allowed, i.e.:

  * clone
  * fetch
  * pull

• WRITERS*In addition to what READERS can do:

  * Fast-forward push (except to the "master" branch).
  * Create new branches.
  * Create tags.

• MASTERS*In addition to what WRITERS can do:

  * Fast-forward push to "master".

• MANAGERS*In addition to what MASTERS can do:

  * Delete branches.
  * Delete tags.
  * Non fast-forward push, i.e. push amended commits, rebased or rewound branches.

• ADMINS*In addition to what MANAGERS can do:

  * Managing access to the repository by assigning/revoking roles, just like the owner of the repository.

If more than one role is assigned, the role which allows the most will be in effect.

To list which roles are assigned for a repository, run the *perm* with the *-l* option command using SSH:

<verbatim> ssh git@vcs.service.rug.nl perms -l abc/example </verbatim>

---+++ Further information

  * "Gitolite" is used for hosting git on this server. So for all the details, refer to Gitolite's documentation: [[1][2]]
  * A quick tutorial about SSH public keys is here: [[3][4]]