Update documentation and improve coverage

Author: tz-lom

src/deployconfig.jl

@@ -297,6 +297,9 @@ end
 
 Implementation of `DeployConfig` for deploying from GitHub Actions.
 
+For self-hosted GitHub installation use `GitHubActions(host, pages_url)` constructor 
+  to specify the host name and a **full path** to the GitHub pages location.
+
 The following environment variables influences the build
 when using the `GitHubActions` configuration:
 
@@ -311,6 +314,10 @@ when using the `GitHubActions` configuration:
  - `GITHUB_TOKEN` or `DOCUMENTER_KEY`: used for authentication with GitHub,
    see the manual section for [GitHub Actions](@ref) for more information.
 
+ - `GITHUB_API_URL`: defines URL to GitHub API.
+
+ - `GITHUB_ACTOR`: Name of the person/app that initiated the workflow.
+
 The `GITHUB_*` variables are set automatically on GitHub Actions, see the
 [documentation](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables).
 """
@@ -559,8 +566,8 @@ function post_github_status(cfg::GitHubActions, type::S, deploydocs_repo::S, sha
         io = IOBuffer()
         res = run(pipeline(cmd; stdout = io, stderr = devnull))
         @debug "Response of curl POST request" response = String(take!(io))
-    catch
-        @debug "Failed to post status"
+    catch e
+        @debug "Failed to post status" exception = e
     end
     return nothing
 end

src/utilities/Remotes.jl

@@ -106,8 +106,8 @@ end
 const GITHUB_HOST = "github.com"
 
 """
-    GitHub(user :: AbstractString, repo :: AbstractString)
-    GitHub(remote :: AbstractString)
+    GitHub(user :: AbstractString, repo :: AbstractString, [host :: AbstractString])
+    GitHub(remote :: AbstractString, [host :: AbstractString])
 
 Represents a remote Git repository hosted on GitHub. The repository is identified by the
 names of the user (or organization) and the repository: `GitHub(user, repository)`. E.g.:
@@ -120,6 +120,8 @@ makedocs(
 
 The single-argument constructor assumes that the user and repository parts are separated by
 a slash (e.g. `JuliaDocs/Documenter.jl`).
+
+A `host` can be provided to point to the location of the self-hosted GitHub installation.
 """
 struct GitHub <: Remote
     user::String

test/deployconfig.jl

@@ -1516,3 +1516,52 @@ end
         @test length(r.stdout) > 0
     end
 end
+
+@testset "post_status" begin
+    if Sys.which("curl") === nothing
+        @warn "'curl' binary not found, skipping related tests."
+    else
+        @testset "Default GitHubActions" begin
+            buffer = IOBuffer()
+            logger = SimpleLogger(buffer, Logging.Debug)
+            with_logger(logger) do
+                withenv(
+                    "GITHUB_EVENT_NAME" => "push",
+                    "GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
+                    "GITHUB_REF" => "refs/tags/v1.2.3",
+                    "GITHUB_ACTOR" => "github-actions",
+                    "GITHUB_SHA" => "407d4b94",
+                    "GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
+                    "GITHUB_API_URL" => "badurl://api.github.com" # use bad url protocol to trigger CURL failure
+                ) do
+                    cfg = Documenter.GitHubActions()
+                    Documenter.post_status(cfg; type = "success", repo = "github.com/JuliaDocs/Documenter.jl")
+                end
+            end
+            logged = read(seek(buffer, 0), String)
+            @test occursin("""`curl -sX POST -H 'Authorization: token SGVsbG8sIHdvcmxkLg==' -H 'User-Agent: Documenter.jl' -H 'Content-Type: application/json' -d '{"target_url":"https://JuliaDocs.github.io/Documenter.jl/","context":"documenter/deploy","description":"Documentation build succeeded","state":"success"}' badurl://api.github.com/repos/JuliaDocs/Documenter.jl/statuses/407d4b94`""", logged)
+        end
+
+        @testset "Self-hosted GitHubActions" begin
+            buffer = IOBuffer()
+            logger = SimpleLogger(buffer, Logging.Debug)
+            with_logger(logger) do
+                withenv(
+                    "GITHUB_EVENT_NAME" => "push",
+                    "GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
+                    "GITHUB_REF" => "refs/tags/v1.2.3",
+                    "GITHUB_ACTOR" => "github-actions",
+                    "GITHUB_SHA" => "407d4b94",
+                    "GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
+                    "GITHUB_API_URL" => "badurl://api.github.selfhosted" # use bad url protocol to trigger CURL failure
+                ) do
+                    cfg = Documenter.GitHubActions("github.selfhosted", "pages.selfhosted")
+                    Documenter.post_status(cfg; type = "success", repo = "github.selfhosted/JuliaDocs/Documenter.jl")
+                end
+            end
+            logged = read(seek(buffer, 0), String)
+            @test occursin("""`curl -sX POST -H 'Authorization: token SGVsbG8sIHdvcmxkLg==' -H 'User-Agent: Documenter.jl' -H 'Content-Type: application/json' -d '{\"target_url\":\"pages.selfhosted\",\"context\":\"documenter/deploy\",\"description\":\"Documentation build succeeded\",\"state\":\"success\"}' badurl://api.github.selfhosted/repos/JuliaDocs/Documenter.jl/statuses/407d4b94`""", logged)
+        end
+
+    end
+end