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
|
# 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. Limit 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
## Code status
[](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
[](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
[](https://codeclimate.com/github/gitlabhq/gitlab-shell)
## Requirements
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/
We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy)
of supporting the current stable version and the previous two major versions.
## Check
Checks if GitLab API access and redis via internal API can be reached:
make check
## Compile
Builds the `gitlab-shell` binaries, placing them into `bin/`.
make compile
## Install
Builds the `gitlab-shell` binaries and installs them onto the filesystem. The
default location is `/usr/local`, but can be controlled by use of the `PREFIX`
and `DESTDIR` environment variables.
make install
## Setup
This command is intended for use when installing GitLab from source on a single
machine. In addition to compiling the gitlab-shell binaries, it ensures that
various paths on the filesystem exist with the correct permissions. Do not run
it unless instructed to by your installation method documentation.
make setup
## Testing
Run tests:
bundle install
make test
Run gofmt:
make verify
Run both test and verify (the default Makefile target):
bundle install
make validate
### Gitaly
Some tests need a Gitaly server. The
[`docker-compose.yml`](./docker-compose.yml) file will run Gitaly on
port 8075. To tell the tests where Gitaly is, set
`GITALY_CONNECTION_INFO`:
export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}'
make test
If no `GITALY_CONNECTION_INFO` is set, the test suite will still run, but any
tests requiring Gitaly will be skipped. They will always run in the CI
environment.
## Git LFS remark
Starting with GitLab 8.12, GitLab supports Git LFS authentication through SSH.
## Logging Guidelines
In general, it should be possible to determine the structure, but not content,
of a gitlab-shell or gitlab-sshd session just from inspecting the logs. Some
guidelines:
- We use [`gitlab.com/gitlab-org/labkit/log`](https://pkg.go.dev/gitlab.com/gitlab-org/labkit/log)
for logging functionality
- **Always** include a correlation ID
- Log messages should be invariant and unique. Include accessory information in
fields, using `log.WithField`, `log.WithFields`, or `log.WithError`.
- Log success cases as well as error cases
- Logging too much is better than not logging enough. If a message seems too
verbose, consider reducing the log level before removing the message.
## Releasing
See [PROCESS.md](./PROCESS.md)
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
See [LICENSE](./LICENSE).
|
