As we reevaluate how to best support and maintain Staging Ref in the future, we encourage development teams using this environment to highlight their use cases in the following issue: https://gitlab.com/gitlab-com/gl-infra/software-delivery/framework/software-delivery-framework-issue-tracker/-/issues/36.

Skip to content
Snippets Groups Projects
Commit ad1d7536 authored by Amy Qualls's avatar Amy Qualls
Browse files

Major README revisions for tone and style 

Shift commands from one-per-subheading to an unordered list, which is
easier to scan. Line wraps. Capitalization, spelling, word use. Move
the requirements section closer to the top of the page; we shouldn't
bury this information as the page gets longer.
parent 0bd9ce8c
No related branches found
No related tags found
Hide whitespace changes
Inline Side-by-side
Showing
with 58 additions and 67 deletions
README.md
+ 58
− 67
View file @ ad1d7536
@@ -4,26 +4,37 @@
# GitLab Shell
GitLab Shell is a SSH server, configured to handing git SSH sessions for GitLab. GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh.
GitLab Shell is a SSH server, configured to handle Git SSH sessions for GitLab.
GitLab Shell is not a Unix shell, nor a replacement for Bash or Zsh:
The purpose of GitLab Shell is to limit shell access to specific `git` commands, and provide authorization and transport for these commands.
- It limits shell access to specific `git` commands.
- It provides authorization and transport for these commands.
## 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 [golang.org](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.
## Handling `git` SSH sessions
When you access the GitLab server over SSH then GitLab Shell will:
When you access the GitLab server over SSH, GitLab Shell:
1. Limit you to `git push` and `git pull`, `git fetch` commands only
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
1. Limits you to `git push`, `git pull`, and `git fetch` commands only.
1. Calls the GitLab Rails API to check if you are authorized, and what Gitaly server your repository is on.
1. Copies data back and forth between the SSH client and the Gitaly server.
### `git pull` over SSH
git pull over SSH -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> establish Gitaly session
Git pull over SSH -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> establish Gitaly session
### `git push` over SSH
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 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
For more details see [Architecture](doc/architecture.md)
@@ -33,87 +44,67 @@ GitLab Shell modifies the `authorized_keys` file on the client machine.
- TODO some details needed here.
### Runs on Port 22
### Runs on port 22
GitLab Shell runs on `port 22` on an Omnibus installation. A "regular" SSH service would need to be configured to run on an alternative port.
GitLab Shell runs on `port 22` on an Omnibus installation. To use a regular SSH
service, configure it on an alternative port.
### Accessing GitLab using `https`
### Access GitLab with `https`
If you access a GitLab server over HTTP(S) you end up in [gitlab-workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse).
If you access a GitLab server over HTTP(S) you end up in
[`gitlab-workhorse`](https://gitlab.com/gitlab-org/gitlab-workhorse).
## `gitlab-sshd`
See [gitlab-sshd](doc/gitlab-sshd)
## 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.
See [`gitlab-sshd`](doc/gitlab-sshd).
make setup
## Commands
- `make check`: Checks if GitLab API access and Redis (via internal API) can be reached
- `make compile`: Builds the `gitlab-shell` binaries, placing them into `bin/`.
- `make install`: Builds the `gitlab-shell` binaries and installs them onto the
file system. The default location is `/usr/local`, but you can change it with the `PREFIX`
and `DESTDIR` environment variables.
- `make setup`: Don't run this command unless instructed to by your installation method
documentation. Used when installing GitLab from source on a single machine. Compiles
the `gitlab-shell` binaries, and ensures that file system paths exist and contain
correct permissions.
### Testing
Run tests:
bundle install
make test
```shell
bundle install
make test
```
Run `gofmt`:
make verify
```shell
make verify
```
Run both test and verify (the default Makefile target):
bundle install
make validate
```shell
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`:
[`docker-compose.yml`](docker-compose.yml) file runs Gitaly on port 8075.
To tell the tests the location of Gitaly, set `GITALY_CONNECTION_INFO`:
export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}'
make test
```plaintext
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.
If no `GITALY_CONNECTION_INFO` is set, the test suite still runs, but any
tests requiring Gitaly are skipped. These tests always run in the CI environment.
## References
@@ -125,12 +116,12 @@ GitLab supports Git LFS authentication through SSH.
## Releasing
See [PROCESS.md](./PROCESS.md)
See [PROCESS.md](PROCESS.md)
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
See [LICENSE](./LICENSE).
See [LICENSE](LICENSE).
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

As we reevaluate how to best support and maintain Staging Ref in the future, we encourage development teams using this environment to highlight their use cases in the following issue: https://gitlab.com/gitlab-com/gl-infra/software-delivery/framework/software-delivery-framework-issue-tracker/-/issues/36.