diff --git a/CHANGELOG b/CHANGELOG
index 07274ab5c1de23f8c5baef4ff3583ce7939ae92d..584e60a0e06fbaab561c88adcad9712a8253fcf7 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -6,6 +6,8 @@ v 8.7.0 (unreleased)
   - Load award emoji images separately unless opening the full picker. Saves several hundred KBs of data for most pages. (Connor Shea)
   - All images in discussions and wikis now link to their source files !3464 (Connor Shea).
   - Return status code 303 after a branch DELETE operation to avoid project deletion (Stan Hu)
+  - Add setting for customizing the list of trusted proxies !3524
+  - Fix `signed_in_ip` being set to 127.0.0.1 when using a reverse proxy !3524
   - Improved Markdown rendering performance !3389 (Yorick Peterse)
   - Don't attempt to look up an avatar in repo if repo directory does not exist (Stan Hu)
   - Expose project badges in project settings
diff --git a/config/gitlab.yml.example b/config/gitlab.yml.example
index 35c7c425a5a75999bae5fd14c28cea605337c9fa..56caee47c97dc3d31783548b5c3f0690195167b1 100644
--- a/config/gitlab.yml.example
+++ b/config/gitlab.yml.example
@@ -46,6 +46,15 @@ production: &base
     #
     # relative_url_root: /gitlab
 
+    # Trusted Proxies
+    # Customize if you have GitLab behind a reverse proxy which is running on a different machine.
+    # Add the IP address for your reverse proxy to the list, otherwise users will appear signed in from that address.
+    trusted_proxies:
+      # Examples:
+      #- 192.168.1.0/24
+      #- 192.168.2.1
+      #- 2001:0db8::/32
+
     # Uncomment and customize if you can't use the default user to run GitLab (default: 'git')
     # user: git
 
diff --git a/doc/install/installation.md b/doc/install/installation.md
index f8f7d6a9ebedfb54fcc0669164eb63310d403a7a..bfea4ce193eab024c190f4708756c38f2865fe0a 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -530,6 +530,15 @@ See the [omniauth integration document](../integration/omniauth.md)
 GitLab can build your projects. To enable that feature you need GitLab Runners to do that for you.
 Checkout the [GitLab Runner section](https://about.gitlab.com/gitlab-ci/#gitlab-runner) to install it
 
+### Adding your Trusted Proxies
+
+If you are using a reverse proxy on an separate machine, you may want to add the
+proxy to the trusted proxies list. Otherwise users will appear signed in from the
+proxy's IP address.
+
+You can add trusted proxies in `config/gitlab.yml` by customizing the `trusted_proxies`
+option in section 1. Please restart GitLab after editing this file.
+
 ### Custom Redis Connection
 
 If you'd like Resque to connect to a Redis server on a non-standard port or on a different host, you can configure its connection string via the `config/resque.yml` file.