diff options
| -rw-r--r-- | README.md | 76 |
1 files changed, 38 insertions, 38 deletions
@@ -1,54 +1,53 @@ -# GitLab Shell +[](https://gitlab.com/gitlab-org/gitlab-shell/commits/master) +[](https://semaphoreapp.com/gitlabhq/gitlab-shell) +[](https://codeclimate.com/github/gitlabhq/gitlab-shell) +[](https://coveralls.io/r/gitlabhq/gitlab-shell) -## GitLab Shell handles git commands for GitLab +# GitLab Shell -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. +GitLab Shell handles git commands for GitLab and modifies the server's list of +authorized keys. It is not a Unix shell nor a replacement for Bash or Zsh. -When you access the GitLab server over ssh then GitLab Shell will: +When predefined git commands (`git push`, `git pull`, `git annex`) are passed to +to the server over `ssh`, 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 execute the action you requested +1. Execute the pre-receive hooks (called "Git Hooks" in GitLab Enterprise Edition) +1. Execute 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: +These steps are carried out differently for push and pull requests made over http(s): -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 +**When you pull from a git repository over http(s)**, the GitLab Rails app handles +authentication and execution entirely on its own. -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). +**When you push to a git repository over http(s)**, the GitLab Rails app first +delegates authentication and execution to GitLab Shell. -An overview of the four cases described above: +This is because GitLab Rails doesn't have logic for interpreting git push +commands over http(s). This logic is kept in one place (GitLab Shell) so it can +be reused for commands passed over ssh. -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 +Similarly, GitLab Shell does not have logic for conducting authorization. GitLab +Shell executes all push commands before conducting authorization, relying on +pre-receive hooks to do so by triggering API calls to gitlab-rails to check +authorization. -## Code status +Steps for these four modes of access are represented here: -[](https://gitlab.com/gitlab-org/gitlab-shell/commits/master) -[](https://semaphoreapp.com/gitlabhq/gitlab-shell) -[](https://codeclimate.com/github/gitlabhq/gitlab-shell) -[](https://coveralls.io/r/gitlabhq/gitlab-shell) +- **pull over ssh** -> received by gitlab-shell -> API call to gitlab-rails (authorization) -> accept or decline -> git command executed +- **pull over http(s)** -> received by gitlab-rails -> authorization handled internally by gitlab-rails -> accept or decline -> git command executed + +- **push over ssh** -> received by gitlab-shell -> git command executed -> gitlab-shell pre-receive hook invoked -> API call to gitlab-rails (authorization) -> accept or decline push +- **push over http(s)** -> received by gitlab-rails -> git command executed -> gitlab-shell pre-receive hook invoked -> API call to gitlab-rails (authorization) -> accept or decline push -## Requirements +## System 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: ``` @@ -65,16 +64,17 @@ cd ruby-2.1.5 make sudo make install ``` +## Shell Commands -## Setup +### Setup ./bin/install -## Check +### Check ./bin/check -## Repos +### Repos Add repo: @@ -109,7 +109,7 @@ Gc repo: ./bin/gitlab-projects gc gitlab/gitlab-ci.git -## Keys +### Keys Add key: @@ -128,6 +128,6 @@ Remove all keys from authorized_keys file: ./bin/gitlab-keys clear -## Git LFS remark +## A Note about Git LFS Starting with GitLab 8.12, GitLab supports Git LFS authentication through ssh. |