GitLab Shell handles git SSH sessions for GitLab
GitLab Shell handles git SSH sessions 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:
- Limits you to predefined git commands (git push, git pull).
- Call the GitLab Rails API to check if you are authorized, and what Gitaly server your repository is on
- Copy data back and forth between the SSH client and the Gitaly server
If you access a GitLab server over HTTP(S) you end up in gitlab-workhorse.
An overview of the four cases described above:
- git pull over SSH -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> establish Gitaly session
- git push over SSH -> gitlab-shell (git command is not executed yet) -> establish Gitaly session -> (in Gitaly) gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
The gitlab-shell repository used to also contain the Git hooks that allow GitLab to validate Git pushes (e.g. "is this user allowed to push to this protected branch"). These hooks also trigger events in GitLab (e.g. to start a CI pipeline after a push).
We are in the process of moving these hooks to Gitaly, because Git hooks require direct disk access to Git repositories, and that is only possible on Gitaly servers. It makes no sense to have to install gitlab-shell on Gitaly servers.
As of GitLab 11.10 the actual Git hooks are in the Gitaly repository, but gitlab-shell must still be installed on Gitaly servers because the hooks rely on configuration data (e.g. the GitLab internal API URL) that is not yet available in Gitaly itself. Also see the transition plan.
GitLab Shell is written in Go, and needs a Go compiler to build. It still requires Ruby to build and test, but not to run.
Download and install the current version of Go from https://golang.org/dl/
Checks if GitLab API access and redis via internal API can be reached:
bundle install make test
Run gofmt and rubocop:
bundle install make verify
Run both test and verify (the default Makefile target):
bundle install make validate
Git LFS remark
Starting with GitLab 8.12, GitLab supports Git LFS authentication through SSH.
Releasing a new version
GitLab Shell is versioned by git tags, and the version used by the Rails
application is stored in
For each version, there is a raw version and a tag version:
- The raw version is the version number. For instance,
- The tag version is the raw version prefixed with
v. For instance,
To release a new version of GitLab Shell and have that version available to the Rails application:
- Create a merge request to update the
CHANGELOGwith the tag version and the
VERSIONfile with the raw version.
- Ask a maintainer to review and merge the merge request. If you're already a maintainer, second maintainer review is not required.
- Add a new git tag with the tag version.
GITLAB_SHELL_VERSIONin the Rails application to the raw version. (Note: this can be done as a separate MR to that, or in and MR that will make use of the latest GitLab Shell changes.)