diff --git a/README.md b/README.md
index 41eeb1db94..6650c1c452 100644
--- a/README.md
+++ b/README.md
@@ -253,7 +253,7 @@ you'd prefer to have the containers run in the background, you can use
 
 If you want to build the Zulip image yourself, you can do that by
 running `docker-compose build`; see also
-[the documentation on building a custom Git version version](#upgrading-from-a-git-repository).
+[the documentation on building a custom Git version version](/UPGRADING.md#upgrading-from-a-git-repository).
 
 ### Connecting to your Zulip server
 
diff --git a/UPGRADING.md b/UPGRADING.md
index f8c5a6a6fe..378f1bff1b 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -85,12 +85,13 @@ docker-compose exec -u zulip zulip cat /home/zulip/deployments/current/version.p
        args:
          # Change these if you want to build zulip from a different repo/branch
          ZULIP_GIT_URL: https://github.com/zulip/zulip.git
-         ZULIP_GIT_REF: master
+         ZULIP_GIT_REF: "refs/remotes/origin/master"
    ```
 
    You can set `ZULIP_GIT_URL` to any clone of the zulip/zulip git repository,
-   and `ZULIP_GIT_REF` to be any ref name in that repository (e.g. `master` or
-   `1.9.0` or `445932cc8613c77ced023125248c8b966b3b7528`).
+   and `ZULIP_GIT_REF` to be any fully qualified git ref name in that repository
+   (e.g. `refs/remotes/origin/master` or `refs/remotes/origin/1.9.0`
+   or `refs/remotes/origin/445932cc8613c77ced023125248c8b966b3b7528`).
 
 2. Run `docker-compose build zulip` to build a Zulip Docker image from the
    specified Git version.