diff options
author | Dmitriy Zaporozhets <dzaporozhets@gitlab.com> | 2015-02-21 20:54:21 +0000 |
---|---|---|
committer | Dmitriy Zaporozhets <dzaporozhets@gitlab.com> | 2015-02-21 20:54:21 +0000 |
commit | 926bef44f0c14a2ef22406c3fe885cd0be2903ae (patch) | |
tree | 022fa1d378fe60f5106e6693ed5c3376ddf7ed79 | |
parent | e780ba06da1c7f2ec475b26ccff9a947b0074fcd (diff) | |
parent | 9b089f955ff8df8ad3328ee0faa19acfcf8b05b4 (diff) | |
download | gitlab-shell-926bef44f0c14a2ef22406c3fe885cd0be2903ae.tar.gz |
Merge branch 'better-readme' into 'master'
Update readme after Saturday morning conversation with Dmitriy.
See merge request !61
-rw-r--r-- | README.md | 63 |
1 files changed, 58 insertions, 5 deletions
@@ -1,8 +1,42 @@ -# gitlab-shell: ssh access and repository management +# GitLab Shell -GitLab Shell is an application that allows you to execute git commands -and provide ssh access to git repositories. -It is not a Unix shell nor a replacement for Bash or Zsh. +## GitLab Shell handles git commands for GitLab + +GitLab Shell handles git commands for GitLab and modifies the list of authorized keys. +GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh. + +When you access the GitLab server over ssh then GitLab Shell will: + +1. Limits you to predefined git commands (git push, git pull, git annex). +1. Call the GitLab Rails API to check if you are authorized +1. It will execute the pre-receive hooks (called Git Hooks in GitLab Enterprise Edition) +1. It will excute the action you requested +1. Process the GitLab post-receive actions +1. Process any custom post-receive actions + +If you access a GitLab server over http(s) what happens depends on if you pull from or push to the git repository. +If you pull from git repositories over http(s) the GitLab Rails app will completely handle the authentication and execution. +If you push to git repositories over http(s) the GitLab Rails app will not handle any authentication or execution but it will delegate the following to GitLab Shell: + +1. Call the GitLab Rails API to check if you are authorized +1. It will execute the pre-receive hooks (called Git Hooks in GitLab Enterprise Edition) +1. It will excute the action you requested +1. Process the GitLab post-receive actions +1. Process any custom post-receive actions + +Maybe you wonder why in the case of git push over http(s) the Rails app doesn't handle authentication before delegating to GitLab Shell. +This is because GitLab Rails doesn't have the logic to interpret git push commands. +The idea is to have these interpretation code in only one place and this is GitLab Shell so we can reuse it for ssh access. +Actually GitLab Shell executes all git push commands without checking authorizations and relies on the pre-receive hooks to check authorizations. +When you do a git pull command the authorizations are checked before executing the commands (either in GitLab Rails or GitLab Shell with an API call to GitLab Rails). +The authorization checks for git pull are much simpler since you only have to check if a user can access the repo (no need to check branch permissions). + +An overview of the four cases described above: + +1. git pull over ssh -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> execute git command +1. git pull over http -> gitlab-rails (AUthorization) -> accept or decline -> execute git command +1. git push over ssh -> gitlab-shell (git command is not executed yet) -> execute git command -> gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push +1. git push over http -> gitlab-rails (git command is not executed yet) -> execute git command -> gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push ## Code status @@ -11,7 +45,26 @@ It is not a Unix shell nor a replacement for Bash or Zsh. [![Code Climate](https://codeclimate.com/github/gitlabhq/gitlab-shell.png)](https://codeclimate.com/github/gitlabhq/gitlab-shell) [![Coverage Status](https://coveralls.io/repos/gitlabhq/gitlab-shell/badge.png?branch=master)](https://coveralls.io/r/gitlabhq/gitlab-shell) -**Requires ruby 1.9+** +## Requirements + +**GitLab shell will always use your system ruby (normally located at /usr/bin/ruby) and will not use the ruby your installed with a ruby version manager (such as RVM).** +It requires ruby 2.0 or higher. +Please uninstall any old ruby versions from your system: + +``` +sudo apt-get remove ruby1.8 +``` + +Download Ruby and compile it with: + +``` +mkdir /tmp/ruby && cd /tmp/ruby +curl -L --progress http://cache.ruby-lang.org/pub/ruby/2.1/ruby-2.1.5.tar.gz | tar xz +cd ruby-2.1.5 +./configure --disable-install-rdoc +make +sudo make install +``` ## Setup |