diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1bf60b0fbf..76a6efaf80 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@
 
 * ![Enhancement][badge-enhancement] When deploying on CI with `deploydocs`, the build information in the version number (i.e. what comes after `+`) is now discarded when determining the destination directory. This allows custom tags to be used to fix documentation build and deployment issues for versions that have already been registered. ([#1298][github-1298])
 
+* ![Enhancement][badge-enhancement] You can now optionally choose to push pull request preview builds to a different branch and/or different repository than the main docs builds, by setting the optional `branch_previews` and/or `repo_previews` keyword arguments to the `deploydocs` function. Also, you can now optionally choose to use a different SSH key for preview builds, by setting the optional `DOCUMENTER_KEY_PREVIEWS` environment variable; if the `DOCUMENTER_KEY_PREVIEWS` environment variable is not set, then the regular `DOCUMENTER_KEY` environment variable will be used.
+
 * ![Bugfix][badge-bugfix] `Deps.pip` is again a closure and gets executed during the `deploydocs` call, not before it. ([#1240][github-1240])
 
 ## Version `v0.24.10`
diff --git a/docs/src/man/hosting.md b/docs/src/man/hosting.md
index 7e9af35485..330abe0a56 100644
--- a/docs/src/man/hosting.md
+++ b/docs/src/man/hosting.md
@@ -421,6 +421,7 @@ Documenter.deploy_folder
 Documenter.authentication_method
 Documenter.authenticated_repo_url
 Documenter.documenter_key
+Documenter.documenter_key_previews
 Documenter.Travis
 Documenter.GitHubActions
 ```
diff --git a/src/Documenter.jl b/src/Documenter.jl
index 310cfc8a7d..9dd4f64403 100644
--- a/src/Documenter.jl
+++ b/src/Documenter.jl
@@ -305,7 +305,9 @@ include("deployconfig.jl")
         devbranch = "master",
         devurl = "dev",
         versions = ["stable" => "v^", "v#.#", devurl => devurl],
-        push_preview = false
+        push_preview    = false,
+        repo_previews   = repo,
+        branch_previews = branch,
     )
 
 Converts markdown files generated by [`makedocs`](@ref) to HTML and pushes them to `repo`.
@@ -394,6 +396,12 @@ 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.
 
+**`branch_previews`** is the branch to which pull request previews are deployed.
+It defaults to the value of `branch`.
+
+**`repo_previews`** is the remote repository to which pull request previews are
+deployed. It defaults to the value of `repo`.
+
 # Releases vs development branches
 
 [`deploydocs`](@ref) will automatically figure out whether it is deploying the documentation
@@ -418,6 +426,9 @@ function deploydocs(;
         repo   = error("no 'repo' keyword provided."),
         branch = "gh-pages",
 
+        repo_previews   = repo,
+        branch_previews = branch,
+
         deps   = nothing,
         make   = nothing,
 
@@ -429,8 +440,20 @@ function deploydocs(;
         push_preview::Bool = false,
     )
 
-    subfolder = deploy_folder(deploy_config; repo=repo, devbranch=devbranch, push_preview=push_preview, devurl=devurl)
-    if subfolder !== nothing
+    deploy_decision = deploy_folder(deploy_config;
+                                    branch=branch,
+                                    branch_previews=branch_previews,
+                                    devbranch=devbranch,
+                                    devurl=devurl,
+                                    push_preview=push_preview,
+                                    repo=repo,
+                                    repo_previews=repo_previews)
+    if deploy_decision.all_ok
+        deploy_branch = deploy_decision.branch
+        deploy_repo = deploy_decision.repo
+        deploy_subfolder = deploy_decision.subfolder
+        deploy_is_preview = deploy_decision.is_preview
+
         # Add local bin path if needed.
         Deps.updatepath!()
         # Install dependencies when applicable.
@@ -461,13 +484,14 @@ function deploydocs(;
                 @debug "running extra build steps."
                 make()
             end
-            @debug "pushing new documentation to remote: '$repo:$branch'."
+            @debug "pushing new documentation to remote: '$deploy_branch:$branch'."
             mktempdir() do temp
                 git_push(
-                    root, temp, repo;
-                    branch=branch, dirname=dirname, target=target,
-                    sha=sha, deploy_config=deploy_config, subfolder=subfolder,
+                    root, temp, deploy_repo;
+                    branch=deploy_branch, dirname=dirname, target=target,
+                    sha=sha, deploy_config=deploy_config, subfolder=deploy_subfolder,
                     devurl=devurl, versions=versions, forcepush=forcepush,
+                    is_preview=deploy_is_preview,
                 )
             end
         end
@@ -488,6 +512,7 @@ function git_push(
         root, temp, repo;
         branch="gh-pages", dirname="", target="site", sha="", devurl="dev",
         versions, forcepush=false, deploy_config, subfolder,
+        is_preview::Bool = false,
     )
     dirname = isempty(dirname) ? temp : joinpath(temp, dirname)
     isdir(dirname) || mkpath(dirname)
@@ -573,7 +598,12 @@ function git_push(
 
         keyfile = abspath(joinpath(root, ".documenter"))
         try
-            write(keyfile, base64decode(documenter_key(deploy_config)))
+            if is_preview
+                keycontent = documenter_key_previews(deploy_config)
+            else
+                keycontent = documenter_key(deploy_config)
+            end
+            write(keyfile, base64decode(keycontent))
         catch e
             @error """
             Documenter failed to decode the DOCUMENTER_KEY environment variable.
diff --git a/src/deployconfig.jl b/src/deployconfig.jl
index 06982d21eb..e1a8951321 100644
--- a/src/deployconfig.jl
+++ b/src/deployconfig.jl
@@ -7,6 +7,14 @@ Abstract type which new deployment configs should be subtypes of.
 """
 abstract type DeployConfig end
 
+Base.@kwdef struct DeployDecision
+    all_ok::Bool
+    branch::String = ""
+    is_preview::Bool = false
+    repo::String = ""
+    subfolder::String = ""
+end
+
 """
     Documenter.documenter_key(cfg::DeployConfig)
 
@@ -20,6 +28,20 @@ function documenter_key(::DeployConfig)
     return ENV["DOCUMENTER_KEY"]
 end
 
+"""
+    Documenter.documenter_key_previews(cfg::DeployConfig)
+
+Return the Base64-encoded SSH private key for the repository.
+Uses the `DOCUMENTER_KEY_PREVIEWS` environment variable if it is defined,
+otherwise uses the `DOCUMENTER_KEY` environment variable.
+
+This method must be supported by configs that push with SSH, see
+[`Documenter.authentication_method`](@ref).
+"""
+function documenter_key_previews(cfg::DeployConfig)
+    return get(ENV, "DOCUMENTER_KEY_PREVIEWS", documenter_key(cfg))
+end
+
 """
     Documenter.deploy_folder(cfg::DeployConfig; repo, devbranch, push_preview, devurl, kwargs...)
 
@@ -125,7 +147,15 @@ function Travis()
 end
 
 # Check criteria for deployment
-function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwargs...)
+function deploy_folder(cfg::Travis;
+                       repo,
+                       repo_previews = repo,
+                       branch = "gh-pages",
+                       branch_previews = branch,
+                       devbranch,
+                       push_preview,
+                       devurl,
+                       kwargs...)
     io = IOBuffer()
     all_ok = true
     ## Determine build type; release, devbranch or preview
@@ -151,6 +181,9 @@ function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwarg
         tag_ok = tag_nobuild !== nothing
         all_ok &= tag_ok
         println(io, "- $(marker(tag_ok)) ENV[\"TRAVIS_TAG\"] contains a valid VersionNumber")
+        deploy_branch = branch
+        deploy_repo = repo
+        is_preview = false
         ## Deploy to folder according to the tag
         subfolder = tag_nobuild
     elseif build_type === :devbranch
@@ -162,6 +195,9 @@ function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwarg
         branch_ok = !isempty(cfg.travis_tag) || cfg.travis_branch == devbranch
         all_ok &= branch_ok
         println(io, "- $(marker(branch_ok)) ENV[\"TRAVIS_BRANCH\"] matches devbranch=\"$(devbranch)\"")
+        deploy_branch = branch
+        deploy_repo = repo
+        is_preview = false
         ## Deploy to deploydocs devurl kwarg
         subfolder = devurl
     else # build_type === :preview
@@ -172,6 +208,9 @@ function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwarg
         btype_ok = push_preview
         all_ok &= btype_ok
         println(io, "- $(marker(btype_ok)) `push_preview` keyword argument to deploydocs is `true`")
+        deploy_branch = branch_previews
+        deploy_repo = repo_previews
+        is_preview = true
         ## deploy to previews/PR
         subfolder = "previews/PR$(something(pr_number, 0))"
     end
@@ -185,7 +224,15 @@ function deploy_folder(cfg::Travis; repo, devbranch, push_preview, devurl, kwarg
     println(io, "- $(marker(type_ok)) ENV[\"TRAVIS_EVENT_TYPE\"]=\"$(cfg.travis_event_type)\" is not \"cron\"")
     print(io, "Deploying: $(marker(all_ok))")
     @info String(take!(io))
-    return all_ok ? subfolder : nothing
+    if all_ok
+        return DeployDecision(; all_ok = true,
+                                branch = deploy_branch,
+                                is_preview = is_preview,
+                                repo = deploy_repo,
+                                subfolder = subfolder)
+    else
+        return DeployDecision(; all_ok = false)
+    end
 end
 
 
@@ -228,7 +275,15 @@ function GitHubActions()
 end
 
 # Check criteria for deployment
-function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl, kwargs...)
+function deploy_folder(cfg::GitHubActions;
+                       repo,
+                       repo_previews = repo,
+                       branch = "gh-pages",
+                       branch_previews = branch,
+                       devbranch,
+                       push_preview,
+                       devurl,
+                       kwargs...)
     io = IOBuffer()
     all_ok = true
     ## Determine build type
@@ -255,6 +310,9 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
         tag_ok = tag_nobuild !== nothing
         all_ok &= tag_ok
         println(io, "- $(marker(tag_ok)) ENV[\"GITHUB_REF\"]=\"$(cfg.github_ref)\" contains a valid VersionNumber")
+        deploy_branch = branch
+        deploy_repo = repo
+        is_preview = false
         ## Deploy to folder according to the tag
         subfolder = m === nothing ? nothing : tag_nobuild
     elseif build_type === :devbranch
@@ -267,6 +325,9 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
         branch_ok = m === nothing ? false : String(m.captures[1]) == devbranch
         all_ok &= branch_ok
         println(io, "- $(marker(branch_ok)) ENV[\"GITHUB_REF\"] matches devbranch=\"$(devbranch)\"")
+        deploy_branch = branch
+        deploy_repo = repo
+        is_preview = false
         ## Deploy to deploydocs devurl kwarg
         subfolder = devurl
     else # build_type === :preview
@@ -278,6 +339,9 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
         btype_ok = push_preview
         all_ok &= btype_ok
         println(io, "- $(marker(btype_ok)) `push_preview` keyword argument to deploydocs is `true`")
+        deploy_branch = branch_previews
+        deploy_repo = repo_previews
+        is_preview = true
         ## deploydocs to previews/PR
         subfolder = "previews/PR$(something(pr_number, 0))"
     end
@@ -299,7 +363,15 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
     end
     print(io, "Deploying: $(marker(all_ok))")
     @info String(take!(io))
-    return all_ok ? subfolder : nothing
+    if all_ok
+        return DeployDecision(; all_ok = true,
+                                branch = deploy_branch,
+                                is_preview = is_preview,
+                                repo = deploy_repo,
+                                subfolder = subfolder)
+    else
+        return DeployDecision(; all_ok = false)
+    end
 end
 
 function authentication_method(::GitHubActions)
diff --git a/test/deployconfig.jl b/test/deployconfig.jl
index 7c18c50f69..7a539ad641 100644
--- a/test/deployconfig.jl
+++ b/test/deployconfig.jl
@@ -11,8 +11,12 @@ using Logging
             "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
         ) do
         cfg = Documenter.Travis()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="dev", push_preview=true) == "v1.2.3"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="dev", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "v1.2.3"
+        @test d.repo == "github.com/JuliaDocs/Documenter.jl.git"
+        @test d.branch == "gh-pages"
         @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
         @test Documenter.authentication_method(cfg) === Documenter.SSH
     end
@@ -26,8 +30,9 @@ using Logging
             "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
         ) do
         cfg = Documenter.Travis()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="dev", push_preview=true) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="dev", push_preview=true)
+        @test !d.all_ok
     end
     # Regular/broken devbranch build
     withenv("TRAVIS_CI" => "true",
@@ -39,10 +44,15 @@ using Logging
             "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
         ) do
         cfg = Documenter.Travis()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=true) == "hello-world"
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="not-master", devurl="hello-world", push_preview=true) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "hello-world"
+        @test d.repo == "github.com/JuliaDocs/Documenter.jl.git"
+        @test d.branch == "gh-pages"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="not-master", devurl="hello-world", push_preview=true)
+        @test !d.all_ok
         @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
     end
     # Regular pull request build
@@ -55,10 +65,15 @@ using Logging
             "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
         ) do
         cfg = Documenter.Travis()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=true) == "previews/PR42"
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=false) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "previews/PR42"
+        @test d.repo == "github.com/JuliaDocs/Documenter.jl.git"
+        @test d.branch == "gh-pages"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=false)
+        @test !d.all_ok
         @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
     end
     # Missing/broken environment variables
@@ -71,8 +86,9 @@ using Logging
             "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.Travis()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=false) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=false)
+        @test !d.all_ok
     end
 end end
 
@@ -86,8 +102,12 @@ end end
             "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="dev", push_preview=true) == "v1.2.3"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="dev", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "v1.2.3"
+        @test d.repo == "github.com/JuliaDocs/Documenter.jl.git"
+        @test d.branch == "gh-pages"
         @test Documenter.authentication_method(cfg) === Documenter.HTTPS
         @test Documenter.authenticated_repo_url(cfg) === "https://github-actions:SGVsbG8sIHdvcmxkLg==@github.com/JuliaDocs/Documenter.jl.git"
     end
@@ -100,8 +120,12 @@ end end
             "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
         ) do
         cfg = Documenter.GitHubActions()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="dev", push_preview=true) == "v1.2.3"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="dev", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "v1.2.3"
+        @test d.repo == "github.com/JuliaDocs/Documenter.jl.git"
+        @test d.branch == "gh-pages"
         @test Documenter.authentication_method(cfg) === Documenter.SSH
         @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
     end
@@ -114,8 +138,9 @@ end end
             "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="dev", push_preview=true) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="dev", push_preview=true)
+        @test !d.all_ok
     end
     # Regular devbranch build with GITHUB_TOKEN
     withenv("GITHUB_EVENT_NAME" => "push",
@@ -126,10 +151,13 @@ end end
             "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=true) == "hello-world"
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="not-master", devurl="hello-world", push_preview=true) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                  devbranch="master", devurl="hello-world", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "hello-world"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="not-master", devurl="hello-world", push_preview=true)
+        @test !d.all_ok
         @test Documenter.authentication_method(cfg) === Documenter.HTTPS
         @test Documenter.authenticated_repo_url(cfg) === "https://github-actions:SGVsbG8sIHdvcmxkLg==@github.com/JuliaDocs/Documenter.jl.git"
     end
@@ -142,10 +170,13 @@ end end
             "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
         ) do
         cfg = Documenter.GitHubActions()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=true) == "hello-world"
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="not-master", devurl="hello-world", push_preview=true) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "hello-world"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="not-master", devurl="hello-world", push_preview=true)
+        @test !d.all_ok
         @test Documenter.authentication_method(cfg) === Documenter.SSH
         @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
     end
@@ -158,10 +189,15 @@ end end
             "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=true) == "previews/PR42"
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="not-master", devurl="hello-world", push_preview=false) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "previews/PR42"
+        @test d.repo == "github.com/JuliaDocs/Documenter.jl.git"
+        @test d.branch == "gh-pages"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="not-master", devurl="hello-world", push_preview=false)
+        @test !d.all_ok
         @test Documenter.authentication_method(cfg) === Documenter.HTTPS
         @test Documenter.authenticated_repo_url(cfg) === "https://github-actions:SGVsbG8sIHdvcmxkLg==@github.com/JuliaDocs/Documenter.jl.git"
     end
@@ -174,13 +210,70 @@ end end
             "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
         ) do
         cfg = Documenter.GitHubActions()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=true) == "previews/PR42"
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="not-master", devurl="hello-world", push_preview=false) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "previews/PR42"
+        @test d.repo == "github.com/JuliaDocs/Documenter.jl.git"
+        @test d.branch == "gh-pages"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="not-master", devurl="hello-world", push_preview=false)
+        @test !d.all_ok
         @test Documenter.authentication_method(cfg) === Documenter.SSH
         @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
     end
+    # Regular pull request build with SSH deploy key (SSH key prioritized), but push previews to a different repo and different branch
+    withenv("GITHUB_EVENT_NAME" => "pull_request",
+            "GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
+            "GITHUB_REF" => "refs/pull/42/merge",
+            "GITHUB_ACTOR" => "github-actions",
+            "GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
+            "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
+        ) do
+        cfg = Documenter.GitHubActions()
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=true,
+                                     repo_previews="github.com/JuliaDocs/Documenter-previews.jl.git",
+                                     branch_previews="gh-pages-previews")
+        @test d.all_ok
+        @test d.subfolder == "previews/PR42"
+        @test d.repo == "github.com/JuliaDocs/Documenter-previews.jl.git"
+        @test d.branch == "gh-pages-previews"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="not-master", devurl="hello-world", push_preview=false,
+                                     repo_previews="",
+                                     branch_previews="")
+        @test !d.all_ok
+        @test Documenter.authentication_method(cfg) === Documenter.SSH
+        @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
+    end
+    # Regular pull request build with SSH deploy key (SSH key prioritized), but push previews to a different repo and different branch; use a different deploy key for previews
+    withenv("GITHUB_EVENT_NAME" => "pull_request",
+            "GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
+            "GITHUB_REF" => "refs/pull/42/merge",
+            "GITHUB_ACTOR" => "github-actions",
+            "GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
+            "DOCUMENTER_KEY" => "SGVsbG8sIHdvcmxkLg==",
+            "DOCUMENTER_KEY_PREVIEWS" => "SGVsbG8sIHdvcmxkLw==",
+        ) do
+        cfg = Documenter.GitHubActions()
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=true,
+                                     repo_previews="github.com/JuliaDocs/Documenter-previews.jl.git",
+                                     branch_previews="gh-pages-previews")
+        @test d.all_ok
+        @test d.subfolder == "previews/PR42"
+        @test d.repo == "github.com/JuliaDocs/Documenter-previews.jl.git"
+        @test d.branch == "gh-pages-previews"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="not-master", devurl="hello-world", push_preview=false,
+                                     repo_previews="",
+                                     branch_previews="")
+        @test !d.all_ok
+        @test Documenter.authentication_method(cfg) === Documenter.SSH
+        @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
+        @test Documenter.documenter_key_previews(cfg) === "SGVsbG8sIHdvcmxkLw=="
+    end
     # Missing environment variables
     withenv("GITHUB_EVENT_NAME" => "push",
             "GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
@@ -190,19 +283,22 @@ end end
             "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="hello-world", push_preview=true) === nothing
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="hello-world", push_preview=true)
+        @test !d.all_ok
     end
 end end
 
 struct CustomConfig <: Documenter.DeployConfig end
-Documenter.deploy_folder(::CustomConfig; kwargs...) = "v1.2.3"
+Documenter.deploy_folder(::CustomConfig; kwargs...) = Documenter.DeployDecision(; all_ok = true, subfolder = "v1.2.3")
 struct BrokenConfig <: Documenter.DeployConfig end
 
 @testset "Custom configuration" begin; with_logger(NullLogger()) do
         cfg = CustomConfig()
-        @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
-                  devbranch="master", devurl="dev", push_preview=true) == "v1.2.3"
+        d = Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
+                                     devbranch="master", devurl="dev", push_preview=true)
+        @test d.all_ok
+        @test d.subfolder == "v1.2.3"
         cfg = BrokenConfig()
         @test (@test_logs (:warn, r"Documenter\.deploy_folder\(::BrokenConfig; kwargs\.\.\.\) not implemented") Documenter.deploy_folder(cfg)) === nothing
         @test (@test_logs (:warn, r"Documenter could not auto-detect") Documenter.deploy_folder(nothing)) === nothing