== 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 - http://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 brownbeagle-gitauth --source http://gems.github.com/
  
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 simplicity purposes, I added the the following to my zsh profile so I always
had it available. If you don't wish to, just use as you would without the alias:

  alias asgit='sudo -H -u git'
  
And finally, to create a settings file and initialize .ssh and authorized_keys, perform the
following:

  asgit 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 you append a 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.

  asgit gitauth install 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 webapp
  
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 http://your-server-ip:8998/

=== Adding Users

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

  gitauth adduser 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 addrepo repo-name
  
Then, for every user who needs access, you do:

  gitauth permissions repo-name user-name permission-type
  
Where permission type is read, write or all. If permission
type isn't specified, it will default to all.

=== 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:

  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