1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
# GitLab Shell
## 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:
1. Limits you to predefined git commands (git push, git pull).
1. Call the GitLab Rails API to check if you are authorized, and what Gitaly server your repository is on
1. 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](https://gitlab.com/gitlab-org/gitlab-workhorse).
An overview of the four cases described above:
1. git pull over SSH -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> establish Gitaly session
1. 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
## Git hooks
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](https://gitlab.com/gitlab-org/gitaly/tree/v1.22.0/ruby/vendor/gitlab-shell/hooks),
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](https://gitlab.com/gitlab-org/gitaly/issues/1226#note_126519133).
## Code status
[](https://gitlab.com/gitlab-org/gitlab-shell/commits/master)
[](https://gitlab.com/gitlab-org/gitlab-shell/commits/master)
[](https://codeclimate.com/github/gitlabhq/gitlab-shell)
## 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
```
To install gitlab-shell you also need a Go compiler version 1.8 or newer. https://golang.org/dl/
## Setup
make setup
## Check
Checks if GitLab API access and redis via internal API can be reached:
make check
## Testing
Run Ruby and Golang tests:
make test
Run Rubocop and gofmt:
make verify
Run both test and verify (the default Makefile target):
make validate
## Git LFS remark
Starting with GitLab 8.12, GitLab supports Git LFS authentication through SSH.
## Migration to Go feature flags
We are starting to migrate some features from Ruby to Go. To be able to do this
incrementally, we hide the Go implementation behind a feature flag.
To enable a feature, modify `migration` option in `config.yml` and ensure `enabled`
is set to `true` and feature to be enabled is added to `features`.
It should look something like this:
```yaml
migration:
enabled: true
features: ['discover']
```
Here are the following features that can be enabled:
- `discover`
- `2fa_recovery_codes`
### Configuring using Omnibus
If you're using Omnibus, these features can be enabled by adding something like this to `gitlab.rb`:
```ruby
gitlab_shell['migration'] = { enabled: true, features: ['discover', '2fa_recovery_codes'] }
```
This is equivalent to having this in `config.yml`:
```yaml
migration:
enabled: true
features: ['discover', '2fa_recovery_codes']
```
## Releasing a new version
GitLab Shell is versioned by git tags, and the version used by the Rails
application is stored in
[`GITLAB_SHELL_VERSION`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/GITLAB_SHELL_VERSION).
For each version, there is a raw version and a tag version:
- The **raw version** is the version number. For instance, `15.2.8`.
- The **tag version** is the raw version prefixed with `v`. For instance, `v15.2.8`.
To release a new version of GitLab Shell and have that version available to the
Rails application:
1. Update the [`CHANGELOG`](CHANGELOG) with the **tag version** and the
[`VERSION`](VERSION) file with the **raw version**.
2. Add a new git tag with the **tag version**.
3. Update `GITLAB_SHELL_VERSION` in 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.)
## Updating VCR fixtures
In order to generate new VCR fixtures you need to have a local GitLab instance
running and have next data:
1. gitlab-org/gitlab-test project.
2. SSH key with access to the project and ID 1 that belongs to Administrator.
3. SSH key without access to the project and ID 2.
You also need to modify `secret` variable at `spec/gitlab_net_spec.rb` so tests
can connect to your local instance.
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
See [LICENSE](./LICENSE).
|
