Skip to content

Commit 4efbbbc

Browse files
amyqIgor Drozdov
amyq
authored and
Igor Drozdov
committed
Incorporate older edits to README
1 parent cdde058 commit 4efbbbc

File tree

3 files changed

+103
-17
lines changed

3 files changed

+103
-17
lines changed

‎README.md

+30-17
Original file line numberDiff line numberDiff line change
@@ -6,41 +6,50 @@ info: To determine the technical writer assigned to the Stage/Group associated w
66

77
# GitLab Shell
88

9-
## GitLab Shell handles git SSH sessions for GitLab
9+
[![pipeline status](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/pipeline.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
10+
[![coverage report](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/coverage.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
11+
[![Code Climate](https://codeclimate.com/github/gitlabhq/gitlab-shell.svg)](https://codeclimate.com/github/gitlabhq/gitlab-shell)
1012

1113
GitLab Shell handles git SSH sessions for GitLab and modifies the list of authorized keys.
1214
GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh.
1315

16+
GitLab supports Git LFS authentication through SSH.
17+
18+
## Requirements
19+
20+
GitLab Shell is written in Go, and needs a Go compiler to build. It still requires
21+
Ruby to build and test, but not to run.
22+
23+
GitLab Shell runs on `port 22` on an Omnibus installation. To use a regular SSH
24+
service, configure it on an alternative port.
25+
26+
Download and install the current version of Go from [golang.org](https://golang.org/dl/)
27+
We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy)
28+
of supporting the current stable version and the previous two major versions.
29+
30+
## How GitLab Shell works
31+
1432
When you access the GitLab server over SSH then GitLab Shell will:
1533

16-
1. Limit you to predefined git commands (git push, git pull).
34+
1. Limit you to predefined git commands (`git push`, `git pull`, `git fetch`).
1735
1. Call the GitLab Rails API to check if you are authorized, and what Gitaly server your repository is on
1836
1. Copy data back and forth between the SSH client and the Gitaly server
1937

2038
If you access a GitLab server over HTTP(S) you end up in [gitlab-workhorse](https://gitlab.com/gitlab-org/gitlab/tree/master/workhorse).
2139

22-
An overview of the four cases described above:
40+
### `git pull` over SSH
2341

2442
1. git pull over SSH -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> establish Gitaly session
25-
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
2643

27-
[Full feature list](doc/features.md)
28-
29-
## Code status
30-
31-
[![pipeline status](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/pipeline.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
32-
[![coverage report](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/coverage.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
33-
[![Code Climate](https://codeclimate.com/github/gitlabhq/gitlab-shell.svg)](https://codeclimate.com/github/gitlabhq/gitlab-shell)
44+
### `git push` over SSH
3445

35-
## Requirements
46+
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
3647

37-
GitLab Shell is written in Go, and needs a Go compiler to build. It still requires
38-
Ruby to build and test, but not to run.
48+
[Full feature list](doc/features.md)
3949

40-
Download and install the current version of Go from https://golang.org/dl/
50+
### Modifies `authorized_keys`
4151

42-
We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy)
43-
of supporting the current stable version and the previous two major versions.
52+
GitLab Shell modifies the `authorized_keys` file on the client machine.
4453

4554
## Rate Limiting
4655

@@ -102,3 +111,7 @@ See [PROCESS.md](./PROCESS.md)
102111
## License
103112

104113
See [LICENSE](./LICENSE).
114+
115+
## Related topics
116+
117+
- [Using the GitLab Shell chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/#using-the-gitlab-shell-chart)

‎doc/architecture.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
stage: Create
3+
group: Source Code
4+
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5+
---
6+
7+
# GitLab Shell architecture
8+
9+
```mermaid
10+
sequenceDiagram
11+
participant Git on client
12+
participant SSH server
13+
participant AuthorizedKeysCommand
14+
participant GitLab Shell
15+
participant Rails
16+
participant Gitaly
17+
participant Git on server
18+
19+
Note left of Git on client: git fetch
20+
Git on client->>+SSH server: ssh git fetch-pack request
21+
SSH server->>+AuthorizedKeysCommand: gitlab-shell-authorized-keys-check git AAAA...
22+
AuthorizedKeysCommand->>+Rails: GET /internal/api/authorized_keys?key=AAAA...
23+
Note right of Rails: Lookup key ID
24+
Rails-->>-AuthorizedKeysCommand: 200 OK, command="gitlab-shell upload-pack key_id=1"
25+
AuthorizedKeysCommand-->>-SSH server: command="gitlab-shell upload-pack key_id=1"
26+
SSH server->>+GitLab Shell: gitlab-shell upload-pack key_id=1
27+
GitLab Shell->>+Rails: GET /internal/api/allowed?action=upload_pack&key_id=1
28+
Note right of Rails: Auth check
29+
Rails-->>-GitLab Shell: 200 OK, { gitaly: ... }
30+
GitLab Shell->>+Gitaly: SSHService.SSHUploadPack request
31+
Gitaly->>+Git on server: git upload-pack request
32+
Note over Git on client,Git on server: Bidirectional communication between Git client and server
33+
Git on server-->>-Gitaly: git upload-pack response
34+
Gitaly -->>-GitLab Shell: SSHService.SSHUploadPack response
35+
GitLab Shell-->>-SSH server: gitlab-shell upload-pack response
36+
SSH server-->>-Git on client: ssh git fetch-pack response
37+
```

‎doc/gitlab-sshd.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
stage: Create
3+
group: Source Code
4+
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5+
---
6+
7+
# gitlab-sshd
8+
9+
`gitlab-sshd` is a binary in [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell)
10+
which runs as a persistent SSH daemon. It will replace `OpenSSH` on GitLab SaaS,
11+
and eventually other cloud-native environments. Instead of running an `sshd` process,
12+
we run a `gitlab-sshd` process that does the same job, in a more focused manner:
13+
14+
```mermaid
15+
sequenceDiagram
16+
participant Git on client
17+
participant GitLab SSHD
18+
participant Rails
19+
participant Gitaly
20+
participant Git on server
21+
22+
Note left of Git on client: git fetch
23+
Git on client->>+GitLab SSHD: ssh git fetch-pack request
24+
GitLab SSHD->>+Rails: GET /internal/api/authorized_keys?key=AAAA...
25+
Note right of Rails: Lookup key ID
26+
Rails-->>-GitLab SSHD: 200 OK, command="gitlab-shell upload-pack key_id=1"
27+
GitLab SSHD->>+Rails: GET /internal/api/allowed?action=upload_pack&key_id=1
28+
Note right of Rails: Auth check
29+
Rails-->>-GitLab SSHD: 200 OK, { gitaly: ... }
30+
GitLab SSHD->>+Gitaly: SSHService.SSHUploadPack request
31+
Gitaly->>+Git on server: git upload-pack request
32+
Note over Git on client,Git on server: Bidirectional communication between Git client and server
33+
Git on server-->>-Gitaly: git upload-pack response
34+
Gitaly -->>-GitLab SSHD: SSHService.SSHUploadPack response
35+
GitLab SSHD-->>-Git on client: ssh git fetch-pack response
36+
```

0 commit comments

Comments
 (0)