Rate limiting documentation

README.md

@@ -94,7 +94,7 @@ 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
+## Git LFS
 
 Starting with GitLab 8.12, GitLab supports Git LFS authentication through SSH.
 
@@ -113,6 +113,16 @@ guidelines:
 - Logging too much is better than not logging enough. If a message seems too
   verbose, consider reducing the log level before removing the message.
 
+## Rate Limiting
+
+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. 
+
+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.
+
+There is also a rate-limiter in place in Gitaly, but the calls will never be made to Gitaly if the rate limit is exceeded in Gitlab Shell (Rails).
+
 ## Releasing
 
 See [PROCESS.md](./PROCESS.md)