Check for empty CI environment variables (#1511)

* Mention that push_review doesn't work from forks
* Check for empty DOCUMENTER_KEY/GITHUB_TOKEN/GITHUB_ACTOR
* Clarify that deploy token and key are not both needed

Author: knuesel

CHANGELOG.md

@@ -6,6 +6,10 @@
 
   - highlight.js has been updated to `v10.5.0`, which also brings various updates to the highlighting of Julia code. Due to the changes in highlight.js, code highlighting will not work on IE11. ([#1503][github-1503])
 
+## Version `v0.26.2`
+
+* ![Bugfix][badge-bugfix] When checking for authentication keys when deploying, Documenter now more appropriately checks if the environment variables are non-empty, rather than just whether they are defined. ([#1511][github-1511])
+
 ## Version `v0.26.1`
 
 * ![Bugfix][badge-bugfix] HTML assets that are copied directly from Documenters source to the build output now has correct file permissions. ([#1497][github-1497])
@@ -729,6 +733,7 @@
 [github-1493]: https://github.com/JuliaDocs/Documenter.jl/pull/1493
 [github-1497]: https://github.com/JuliaDocs/Documenter.jl/pull/1497
 [github-1503]: https://github.com/JuliaDocs/Documenter.jl/pull/1503
+[github-1511]: https://github.com/JuliaDocs/Documenter.jl/pull/1511
 
 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079
 

docs/src/man/hosting.md

@@ -199,8 +199,8 @@ jobs:
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
         run: julia --project=docs/ docs/make.jl
 ```
 

src/Documenter.jl

@@ -405,7 +405,9 @@ the generated html. The following entries are valid in the `versions` vector:
 **`push_preview`** a boolean that specifies if preview documentation should be
 deployed from pull requests or not. If your published documentation is hosted
 at `"https://USER.github.io/PACKAGE.jl/stable`, by default the preview will be
-hosted at `"https://USER.github.io/PACKAGE.jl/previews/PR##"`.
+hosted at `"https://USER.github.io/PACKAGE.jl/previews/PR##"`. This feature
+works for pull requests with head branch in the same repository, i.e. not from
+forks.
 
 **`branch_previews`** is the branch to which pull request previews are deployed.
 It defaults to the value of `branch`.

src/deployconfig.jl

@@ -103,6 +103,8 @@ post_status(; kwargs...) = post_status(auto_detect_deploy_system(); kwargs...)
 
 marker(x) = x ? "✔" : "✘"
 
+env_nonempty(key) = !isempty(get(ENV, key, ""))
+
 #############
 # Travis CI #
 #############
@@ -227,9 +229,9 @@ function deploy_folder(cfg::Travis;
         subfolder = "previews/PR$(something(pr_number, 0))"
     end
     ## DOCUMENTER_KEY should exist (just check here and extract the value later)
-    key_ok = haskey(ENV, "DOCUMENTER_KEY")
+    key_ok = env_nonempty("DOCUMENTER_KEY")
     all_ok &= key_ok
-    println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists")
+    println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists and is non-empty")
     ## Cron jobs should not deploy
     type_ok = cfg.travis_event_type != "cron"
     all_ok &= type_ok
@@ -371,20 +373,20 @@ function deploy_folder(cfg::GitHubActions;
         subfolder = "previews/PR$(something(pr_number, 0))"
     end
     ## GITHUB_ACTOR should exist (just check here and extract the value later)
-    actor_ok = haskey(ENV, "GITHUB_ACTOR")
+    actor_ok = env_nonempty("GITHUB_ACTOR")
     all_ok &= actor_ok
-    println(io, "- $(marker(actor_ok)) ENV[\"GITHUB_ACTOR\"] exists")
+    println(io, "- $(marker(actor_ok)) ENV[\"GITHUB_ACTOR\"] exists and is non-empty")
     ## GITHUB_TOKEN or DOCUMENTER_KEY should exist (just check here and extract the value later)
-    token_ok = haskey(ENV, "GITHUB_TOKEN")
-    key_ok = haskey(ENV, "DOCUMENTER_KEY")
+    token_ok = env_nonempty("GITHUB_TOKEN")
+    key_ok = env_nonempty("DOCUMENTER_KEY")
     auth_ok = token_ok | key_ok
     all_ok &= auth_ok
     if key_ok
-        println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists")
+        println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists and is non-empty")
     elseif token_ok
-        println(io, "- $(marker(token_ok)) ENV[\"GITHUB_TOKEN\"] exists")
+        println(io, "- $(marker(token_ok)) ENV[\"GITHUB_TOKEN\"] exists and is non-empty")
     else
-        println(io, "- $(marker(auth_ok)) ENV[\"DOCUMENTER_KEY\"] or ENV[\"GITHUB_TOKEN\"] exists")
+        println(io, "- $(marker(auth_ok)) ENV[\"DOCUMENTER_KEY\"] or ENV[\"GITHUB_TOKEN\"] exists and is non-empty")
     end
     print(io, "Deploying: $(marker(all_ok))")
     @info String(take!(io))
@@ -413,7 +415,7 @@ function deploy_folder(cfg::GitHubActions;
 end
 
 function authentication_method(::GitHubActions)
-    if haskey(ENV, "DOCUMENTER_KEY")
+    if env_nonempty("DOCUMENTER_KEY")
         return SSH
     else
         @warn "Currently the GitHub Pages build is not triggered when " *
@@ -639,8 +641,8 @@ function deploy_folder(
         deploy_repo = repo
     end
 
-    key_ok = haskey(ENV, "DOCUMENTER_KEY")
-    println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists")
+    key_ok = env_nonempty("DOCUMENTER_KEY")
+    println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists and is non-empty")
     all_ok &= key_ok
 
     print(io, "Deploying to folder $(repr(subfolder)): $(marker(all_ok))")
@@ -782,8 +784,8 @@ function deploy_folder(
         deploy_repo = repo
     end
 
-    key_ok = haskey(ENV, "DOCUMENTER_KEY")
-    println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists")
+    key_ok = env_nonempty("DOCUMENTER_KEY")
+    println(io, "- $(marker(key_ok)) ENV[\"DOCUMENTER_KEY\"] exists and is non-empty")
     all_ok &= key_ok
 
     print(io, "Deploying to folder $(repr(subfolder)): $(marker(all_ok))")