Git server: Difference between revisions

From LWP-Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:
[[Category:version control]]
[[Category:version control]]
__TOC__
 
%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.
This describes how to create repositories on the git server of the RUG and enable other people to access them over the internet.
Line 6: Line 10:
Familiarity is assumed with Git and SSH.
Familiarity is assumed with Git and SSH.


= Repository directory =
 
---+++ Repository directory


Staff members can get a directory in which they can create repositories.
Staff members can get a directory in which they can create repositories.
Line 12: Line 17:
To get an account with a repository directory, please provide us with:
To get an account with a repository directory, please provide us with:


; ''Your e-mail address''
*Your e-mail address*For accounts that can create repositories, *@rug.nl* addresses are required.
: For accounts that can create repositories, <code>@rug.nl</code> addresses are required.
; ''Your SSH public key''
: This is a small text file (~ 1kb). If you use OpenSSH, it is by default <code>~/.ssh/id_rsa.pub</code>. 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.


*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.


= Checking access =
*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:
Run this command to check your access to the server:


<pre>ssh git@vcs.service.rug.nl info</pre>
 
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.
<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:
Example output:


<pre>C    abc/..*
 
<verbatim>
C    abc/..*
R W  one/example
R W  one/example
R    doc</pre>
R    doc
</verbatim>
 
Which means:
Which means:


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




= Creating a repository =
 
---+++ 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:
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:


<pre>git clone git@vcs.service.rug.nl:abc/example</pre>
 
<verbatim>
git clone git@vcs.service.rug.nl:abc/example
</verbatim>
 
Breakdown of the URL:
Breakdown of the URL:


; “git”
"git"The username for SSH. This is always "git".
: The username for SSH. This is always “git”.
 
; “vcs.service.rug.nl”
"vcs.service.rug.nl"DNS name of the Version Control Server. This is always "vcs.service.rug.nl".
: DNS name of the Version Control Server. This is always “vcs.service.rug.nl”.
 
; “abc”
"abc"This is the directory where you can create repositories.
: This is the directory where you can create repositories.
 
; “example”
"example"Name of the (new) repository.
: 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.
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 =
 
---+++ Granting access to others


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


* E-mail address
  * E-mail address
* SSH public key
  * 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.
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.
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 <code>abc/example</code>, run the <code>perms</code> command using SSH like this:
E.g. to enable John Doe to write to your repository *abc/example*, run the *perms* command using SSH like this:


<pre>ssh git@vcs.service.rug.nl perms abc/example + WRITERS john.doe@somehere.net</pre>
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>


<pre>ssh git@vcs.service.rug.nl perms abc/example - WRITERS john.doe@somehere.net</pre>
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.


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


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


; ''READERS''
<verbatim>
: Only reading is allowed, i.e.:
ssh git@vcs.service.rug.nl perms abc/example - WRITERS john.doe@somehere.net
;* clone
</verbatim>
;* fetch
 
;* pull
 
; ''WRITERS''
---++++ Roles
: In addition to what READERS can do:
 
;* Fast-forward push (except to the “master” branch).
There are more levels of access than just "READERS" and "WRITERS". Here is the entire list of roles with their permissions:
;* Create new branches.
 
;* Create tags.
*READERS*Only reading is allowed, i.e.:
; ''MASTERS''
 
: In addition to what WRITERS can do:
  * clone
;* Fast-forward push to “master”.
  * fetch
; ''MANAGERS''
  * pull
: In addition to what MASTERS can do:
 
;* Delete branches.
*WRITERS*In addition to what READERS can do:
;* Delete tags.
 
;* Non fast-forward push, i.e. push amended commits, rebased or rewound branches.
  * Fast-forward push (except to the "master" branch).
; ''ADMINS''
  * Create new branches.
: In addition to what MANAGERS can do:
  * Create tags.
;* Managing access to the repository by assigning/revoking roles, just like the owner of the repository.
 
*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.
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 <code>perm</code> command with the <code>-l</code> using SSH:
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>
 
 


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


= Further information =
---+++ Further information


* “Gitolite” is used for hosting git on this server. So for all the details, refer to Gitolite’s documentation: http://gitolite.com/
  * "Gitolite" is used for hosting git on this server. So for all the details, refer to Gitolite's documentation: [[http://gitolite.com/][http://gitolite.com/]]
* A quick tutorial about SSH public keys is here: http://git-scm.com/book/tr/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key
  * A quick tutorial about SSH public keys is here: [[http://git-scm.com/book/tr/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key][http://git-scm.com/book/tr/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key]]

Revision as of 13:44, 12 January 2016


%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]]