/gitauth

Git Authentication Server

Primary LanguageRubyGNU Affero General Public License v3.0AGPL-3.0

GitAuth - SSH-based authentication for Shared Git Repositories.

If you’ve heard of Gitosis before, GitAuth is like Gitosis but A) in Ruby, B) slightly simpler to get going and C) doesn’t use a git repository to manage users.

At the moment configuration / adding users is done via a single command - gitauth. For usage, see below.

License

GitAuth is licensed under AGPL, with parts of the code being derived from Gitorius - gitorious.org

Installing GitAuth

Getting started is relatively simple. First of, you’ll need to log onto the remote server / your git host. Next, you’ll need to install the gem:

sudo gem install gitauth --source http://gemcutter.org/

Or, if you want to avoid the gems approach, you can use simply clone the repository as follows and use the git submodule setup in order to vendor rack, sinatra and perennial:

git clone git://github.com/brownbeagle/gitauth.git
cd gitauth
git submodule init
git submodule update

With the gitauth binary being in the bin folder.

Once that’s done, the gitauth and gitauth-shell commands should be in your path. Next, you’ll want to (in most cases anyway) use a specific git user to host repositories.

Using the example of ubuntu, we’ll add a git user under which all actions will now take place (note, this is essentially the same as gitosis):

sudo adduser --disabled-password --shell /bin/bash --group --home /home/git --system --gecos 'gitauth user for version control' git

Now, whenever you run the gitauth executable, you’ll do so as the user you just created above. For example purposes, I suggest using the following in order to run all commands as the ‘git’ user:

sudo -H -u git -i

And finally, to create a settings file and initialize .ssh and authorized_keys, perform the following:

gitauth install

Note that when it asks you for the gitauth shell path, the default will lock it to the current gitauth version SO if you want it to stay up to date between gem versions point it to the path for always-current executable (e.g. on Ubuntu 9.04 w/ apt-get ruby + gems, /var/lib/gems/1.8/bin/gitauth-shell)

Also, Note that if use the –admin option with path to a public key to the end of the install command, it will initialize a new admin user who can also login via SSH. e.g.

gitauth install --admin id_rsa.pub

Would initialize an admin user with the given public key.

Note that from now on, all gitauth keys should be run either logged in as git (via the admin user and ssh) or by being prefixed with asgit or “sudo -H -u git”

Web Interface

To start the web interface, just run:

gitauth web-app

The first time you boot the web app, you will be prompted to enter a username and a password. Please do so and then surf to your-server-ip:8998/

For people running passenger, you can simply point it at the public subdirectory and it will act as any normal passenger web app. It’s worth noting that in this approach you need to run gitauth web-app at least once to setup a username and password.

Adding Users

Whenever you want to add a user, it’s as simple as:

gitauth add-user user-name path-to-public-key

Note that if the –admin option is specified, the user will be able to log in to the shell via SSH and will also be able to access any repository.

Adding Repositories

Adding a repository is a two step process. First, you create it:

gitauth add-repo repo-name

If you wish to initialize the repository with a blank commit (so git clone works straight away), simply pass –make-empty / -m as an option. e.g.:

gitauth add-repo repo-name --make-empty

Then, for every user who needs access, you do:

gitauth permissions repo-name user-name --type=permission-type

Where permission type is read, write or all. If permission type isn’t specified, it will default to all. If you wish to remove a user from a repository, you can simply pass use the type as none.

Accessing repos:

Finally, once you’ve added users / repos, using them is as simple as doing the following on each users computer:

git clone git@your-remote-host:repo-name

Or

git clone git@your-remote-host:repo-name.git

Either form working just as well.

Note that for the first time you push, you will need to use the full form (as below) unless you’ve used the –make-empty / -m option when you created the repo.

git push origin master

As it starts as an empty repo.

Alternatively, if you get the error “fatal: no matching remote head” when you clone and it doesn’t create a local copy, you’ll instead have to do the following on your local PC (due to the way git handles remote repositories):

mkdir my-repo
cd my-repo
git init
touch README
git add .
git commit -m "Added blank readme"
git add remote origin git@your-server:my-repo.git
git push origin master