Documentation previews not deployed using v1

[roelstappers]

After updating Documenter to v1 documentation previews of PRs are no longer deployed:

 Warning: GITHUB_TOKEN is missing, unable to verify if PR comes from destination repository -- assuming it doesn't.
└ @ Documenter ~/.julia/packages/Documenter/Meee1/src/deployconfig.jl:518
┌ Info: Deployment criteria for deploying preview build from GitHub Actions:
│ - ✔ ENV["GITHUB_REPOSITORY"]="github.com/Hirlam/HarmonieSystemDocumentation.git" occurs in repo="github.com/Hirlam/HarmonieSystemDocumentation.git"
│ - ✔ ENV["GITHUB_REF"] corresponds to a PR number
│ - ✘ PR originates from the same repository
│ - ✔ `push_preview` keyword argument to deploydocs is `true`
│ - ✔ ENV["GITHUB_ACTOR"] exists and is non-empty
│ - ✔ ENV["DOCUMENTER_KEY"] exists and is non-empty
└ Deploying: ✘

The setup is perhaps slightly non-standard because the github action is running in github.com/Hirlam/Harmonie (a private repo) but documentation should be public so the html pages are deployed to github.com/Hirlam/HarmonieSystemDocumentation.git in make.jl by:

withenv("GITHUB_REPOSITORY" => "github.com/Hirlam/HarmonieSystemDocumentation.git") do 
    deploydocs(
        repo = "github.com/Hirlam/HarmonieSystemDocumentation.git",
        devbranch = "dev-CY46h1",   
        devurl = "dev",       
        push_preview=true
    )
end 

This worked in v0.27. I am using a DOCUMENTER_KEY secret in Hirlam/Harmonie and a Documenter Deploy key in Hirlam/HarmonieSystemDocumentation

[roelstappers]

Note: the Warning: GITHUB_TOKEN is missing is a bit of a red herring. Adding the GITHUB_TOKEN and using

JULIA_DEBUG=Documenter julia --project make.jl

in the github action gives:

┌ Warning: Unable to verify if PR comes from destination repository -- assuming it doesn't.
└ @ Documenter ~/.julia/packages/Documenter/Meee1/src/deployconfig.jl:535
┌ Debug: Running CURL led to an exception:
│   exception =
│    failed process: Process(`curl -s -H 'Authorization: token ***' -H 'User-Agent: Documenter.jl' --fail [https://api.github.com/repos/github.com/Hirlam/HarmonieSystemDocumentation.git/pulls/946`](https://api.github.com/repos/github.com/Hirlam/HarmonieSystemDocumentation.git/pulls/946%60), ProcessExited(22)) [22]
│    
│    Stacktrace:
│      [1] pipeline_error
│        @ ./process.jl:565 [inlined]
│      [2] run(::Base.CmdRedirect; wait::Bool)
│        @ Base ./process.jl:480
│      [3] run
│        @ ./process.jl:477 [inlined]
│      [4] run_and_capture(cmd::Cmd)
│        @ Documenter ~/.julia/packages/Documenter/Meee1/src/deployconfig.jl:543
│      [5] verify_github_pull_repository(repo::String, prnr::Int64)
│        @ Documenter ~/.julia/packages/Documenter/Meee1/src/deployconfig.jl:529
│      [6] deploy_folder(cfg::Documenter.GitHubActions; repo::String, repo_previews::String, branch::String, branch_previews::String, devbranch::String, push_preview::Bool, devurl::String, tag_prefix::String, kwargs::Base.Pairs{Symbol, Union{}, Tuple{}, NamedTuple{(), Tuple{}}})
│        @ Documenter ~/.julia/packages/Documenter/Meee1/src/deployconfig.jl:369
│      [7] deploy_folder
│        @ ~/.julia/packages/Documenter/Meee1/src/deployconfig.jl:306 [inlined]
│      [8] deploydocs(; root::String, target::String, dirname::String, repo::String, branch::String, repo_previews::String, branch_previews::String, deps::Nothing, make::Nothing, devbranch::String, devurl::String, versions::Vector{Any}, forcepush::Bool, deploy_config::Documenter.GitHubActions, push_preview::Bool, tag_prefix::String, archive::Nothing)
│        @ Documenter ~/.julia/packages/Documenter/Meee1/src/deploydocs.jl:213
│      [9] #3
│        @ ~/work/Harmonie/Harmonie/docs/make.jl:41 [inlined]
│     [10] withenv(f::var"#3#4", keyvals::Pair{String, String})
│        @ Base ./env.jl:197
│     [11] top-level scope
│        @ ~/work/Harmonie/Harmonie/docs/make.jl:40
│     [12] include(mod::Module, _path::String)
│        @ Base ./Base.jl:457
│     [13] exec_options(opts::Base.JLOptions)
│        @ Base ./client.jl:307
│     [14] _start()
│        @ Base ./client.jl:522
└ @ Documenter ~/.julia/packages/Documenter/Meee1/src/deployconfig.jl:536
┌ Info: Deployment criteria for deploying preview build from GitHub Actions:
│ - ✔ ENV["GITHUB_REPOSITORY"]="github.com/Hirlam/HarmonieSystemDocumentation.git" occurs in repo="github.com/Hirlam/HarmonieSystemDocumentation.git"
│ - ✔ ENV["GITHUB_REF"] corresponds to a PR number
│ - ✘ PR originates from the same repository
│ - ✔ `push_preview` keyword argument to deploydocs is `true`
│ - ✔ ENV["GITHUB_ACTOR"] exists and is non-empty
│ - ✔ ENV["DOCUMENTER_KEY"] exists and is non-empty
└ Deploying: ✘

So curl is using the wrong url for the repo to check for the PR . PR946 is in Hirlam/Harmonie not in Hirlam/HarmonieSystemDocumentation.

Note for out-of-repo deployment I have to overwrite GITHUB_REPOSITORY as also mentioned in the docs https://documenter.juliadocs.org/stable/man/hosting/#Out-of-repo-deployment

A (dirty) work around is to add

import Documenter: verify_github_pull_repository
verify_github_pull_repository(repo, prnr) = true

To make.jl

[mortenpi]

I assume the change in the behavior is due to this fix? https://github.com/JuliaDocs/Documenter.jl/pull/1969 The check was previously failing as well, but we returned true and carried on with the push?

[mortenpi]

I suppose we could add an argument to deploydocs to set the "source" repo (which can be different from repo, which is the destination repo we wish to deploy into). And it would just default to repo, to maintain the current behavior when it's unset.

[roelstappers]

I assume the change in the behavior is due to this fix? #1969 The check was previously failing as well, but we returned true and carried on with the push?

Yes that seems to be the PR that changed the behavior of verify_github_pull_repository

I suppose we could add an argument to deploydocs to set the "source" repo (which can be different from repo, which is the destination repo we wish to deploy into). And it would just default to repo, to maintain the current behavior when it's unset.

That would be a potential non breaking solution. Adding a sourcerepo keyword would also eliminate the need for the withenv "trick" in:

withenv("GITHUB_REPOSITORY" => "...") do
    deploydocs(...)
end 

But are there situations where sourcerepo would not equal ENV["GITHUB_REPOSITORY"]?

[mortenpi]

But are there situations where sourcerepo would not equal ENV["GITHUB_REPOSITORY"]?

Yes, when the documentation workflow runs on a fork, in which case we want to avoid trying to push. Also, GITHUB_REPOSITORY might not be set if you e.g. are running this workflow on GitLab or some other CI.

[laggvar]

I have also been struggling with this issue recently.

Wouldn't it be simpler to keep repo referring to the "master" repo and add a keyword destrepo or hostrepo (defaulting to repo) to indicate where to upload the build?