Merge branch 'id-add-features-description' into 'main'

Add docs for full feature list

See merge request gitlab-org/gitlab-shell!571

README.md

+---
+stage: Create
+group: Source Code
+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
+---
+
 # GitLab Shell
 
 ## GitLab Shell handles git SSH sessions for GitLab
@@ -18,6 +24,8 @@ 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
 
+[Full feature list](doc/features.md)
+
 ## Code status
 
 [![pipeline status](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/pipeline.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
@@ -94,10 +102,6 @@ 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
-
-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,
@@ -117,7 +121,7 @@ guidelines:
 
 GitLab Shell performs rate-limiting by user account and project for git operations. GitLab Shell accepts git operation requests and then makes a call to the Rails rate-limiter (backed by Redis). If the `user + project` exceeds the rate limit then GitLab Shell will then drop further connection requests for that `user + project`.
 
-The rate-limiter is applied at the git command (plumbing) level. Each command has a rate limit of 600/minute. For example, `git push` has 600/minute and `git pull` has another 600/minute. 
+The rate-limiter is applied at the git command (plumbing) level. Each command has a rate limit of 600/minute. For example, `git push` has 600/minute and `git pull` has another 600/minute.
 
 Because they are using the same plumbing command `git-upload-pack`, `git pull` and `git clone` are in effect the same command for the purposes of rate-limiting.
 

doc/features.md

+---
+stage: Create
+group: Source Code
+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
+---
+
+# Feature list
+
+## Discover
+
+Allows users to identify themselves on an instance via SSH. The command helps to
+confirm quickly whether a user has SSH access to the instance:
+
+```shell
+ssh git@<hostname>
+
+PTY allocation request failed on channel 0
+Welcome to GitLab, @username!
+Connection to staging.gitlab.com closed.
+```
+
+When permission is denied, it returns:
+
+```shell
+ssh git@<hostname>
+git@<hostname>: Permission denied (publickey).
+```
+
+## Git operations
+
+GitLab Shell provides support for Git operations over SSH by processing
+`git-upload-pack`, `git-receive-pack` and `git-upload-archive` SSH commands.
+It limits the set of commands to predefined Git commands:
+
+- `git archive`
+- `git clone`
+- `git pull`
+- `git push`
+
+## Generate new 2FA recovery codes
+
+Enables users to
+[generate new 2FA recovery codes](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#generate-new-recovery-codes-using-ssh):
+
+```plaintext
+ssh git@<hostname> 2fa_recovery_codes
+Are you sure you want to generate new two-factor recovery codes?
+Any existing recovery codes you saved will be invalidated. (yes/no)
+yes
+
+Your two-factor authentication recovery codes are:
+...
+```
+
+## Verify 2FA OTP
+
+Allows users to verify their
+[2FA one-time password (OTP)](https://docs.gitlab.com/ee/security/two_factor_authentication.html#2fa-for-git-over-ssh-operations):
+
+```shell
+ssh git@<hostname> 2fa_verify
+OTP: 347419
+
+OTP validation failed.
+```
+
+## LFS authentication
+
+Enables users to generate credentials for LFS authentication:
+
+```shell
+ssh git@<hostname> git-lfs-authenticate <project-path> <upload/download>
+
+{"header":{"Authorization":"Basic ..."},"href":"https://gitlab.com/user/project.git/info/lfs","expires_in":7200}
+```
+
+## Personal access token
+
+Enables users to use personal access tokens via SSH:
+
+```shell
+ssh git@<hostname> personal_access_token <name> <scope1[,scope2,...]> [ttl_days]
+
+Token:   glpat-...
+Scopes:  api
+Expires: 2022-02-05
+```