Handle DOCUMENTER_KEY errors better in deploydocs (#907)

* Handle DOCUMENTER_KEY errors better in deploydocs

* Print a more helpful error if base64decode fails for the provided key.
* Use SSH batch mode -- this means that SSH won't ask for passphrase
  and time out the Travis build if the SSH key is problematic.
* Also, print a more helpful error if git fetch throws an error, most
  likely due to a key misconfiguration.

Close #697

CHANGELOG.md

@@ -53,6 +53,8 @@
 
 * ![Enhancement][badge-enhancement] The default `documenter.sty` LaTeX preamble now include `\usepackage{graphicx}` ([#898][github-898]).
 
+* ![Enhancement][badge-enhancement] `deploydocs` is now more helpful when it fails to interpret `DOCUMENTER_KEY`. It now also uses the `BatchMode` SSH option and throws an error instead of asking for a passphrase and timing out the Travis build when `DOCUMENTER_KEY` is broken. ([#697][github-697], [#907][github-907])
+
 * ![Enhancement][badge-enhancement] `deploydocs` now have a `forcepush` keyword argument that can be used to
   force-push the built documentation instead of adding a new commit. ([#905][github-905]).
 
@@ -139,6 +141,7 @@
 
 * ![Bugfix][badge-bugfix] At-docs blocks no longer give an error when containing empty lines. ([#823][github-823], [#824][github-824])
 
+[github-697]: https://github.com/JuliaDocs/Documenter.jl/pull/697
 [github-706]: https://github.com/JuliaDocs/Documenter.jl/pull/706
 [github-764]: https://github.com/JuliaDocs/Documenter.jl/pull/764
 [github-789]: https://github.com/JuliaDocs/Documenter.jl/pull/789
@@ -165,6 +168,7 @@
 [github-891]: https://github.com/JuliaDocs/Documenter.jl/pull/891
 [github-898]: https://github.com/JuliaDocs/Documenter.jl/pull/898
 [github-905]: https://github.com/JuliaDocs/Documenter.jl/pull/905
+[github-907]: https://github.com/JuliaDocs/Documenter.jl/pull/907
 
 
 [badge-breaking]: https://img.shields.io/badge/BREAKING-red.svg

src/Documenter.jl

@@ -553,13 +553,22 @@ function git_push(
     dirname = isempty(dirname) ? temp : joinpath(temp, dirname)
     isdir(dirname) || mkpath(dirname)
 
-    keyfile = abspath(joinpath(root, ".documenter"))
     target_dir = abspath(target)
 
     # The upstream URL to which we push new content and the ssh decryption commands.
     upstream = "git@$(replace(repo, "github.com/" => "github.com:"))"
 
-    write(keyfile, String(base64decode(key)))
+    keyfile = abspath(joinpath(root, ".documenter"))
+    try
+        write(keyfile, String(base64decode(key)))
+    catch e
+        @error """
+        Documenter failed to decode the DOCUMENTER_KEY environment variable.
+        Make sure that the environment variable is properly set up as a Base64-encoded string
+        of the SSH private key. You may need to re-generate the keys with DocumenterTools.
+        """
+        rethrow(e)
+    end
     chmod(keyfile, 0o600)
 
     try
@@ -570,6 +579,7 @@ function git_push(
                 StrictHostKeyChecking no
                 HostName github.com
                 IdentityFile $keyfile
+                BatchMode yes
             """
         ) do
             cd(temp) do
@@ -580,7 +590,17 @@ function git_push(
 
                 # Fetch from remote and checkout the branch.
                 run(`git remote add upstream $upstream`)
-                run(`git fetch upstream`)
+                try
+                    run(`git fetch upstream`)
+                catch e
+                    @error """
+                    Git failed to fetch $upstream
+                    This can be caused by a DOCUMENTER_KEY variable that is not correctly set up.
+                    Make sure that the environment variable is properly set up as a Base64-encoded string
+                    of the SSH private key. You may need to re-generate the keys with DocumenterTools.
+                    """
+                    rethrow(e)
+                end
 
                 try
                     run(`git checkout -b $branch upstream/$branch`)