Support SSH deploy keys from GH Actions.

JuliaDocs · Nov 17, 2019 · 0e92e5d · 0e92e5d
1 parent 40c0f53
commit 0e92e5d
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 11 deletions.
diff --git a/docs/src/man/hosting.md b/docs/src/man/hosting.md
@@ -165,6 +165,20 @@ Follow the instructions that are printed out, namely:
 
 ### GitHub Actions
 
+!!! warning
+    The current design of this feature uses [the GitHub Actions authentication token
+    (`GITHUB_TOKEN`)](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token)
+    when publishing documentation onto GitHub Pages. However, when using that token, the website
+    served to the user does not get rebuilt, making it look like the documentation build
+    did not succeed. See [issue #1177](https://github.com/JuliaDocs/Documenter.jl/issues/1177)
+    for more information.
+    Due to this Documenter currently also supports pushing
+    with SSH deploy keys from GitHub Actions, but this may change in the future without prior
+    notice. It is therefore recommended to set both `DOCUMENTER_KEY` and `GITHUB_TOKEN` as secret
+    environment variables.
+    See [Authentication: SSH Deploy Keys](@ref) for how to create and set up the
+    ssh deploy key.
+
 To run the documentation build from GitHub Actions you should add the following to your
 workflow configuration file:
 
@@ -191,6 +205,7 @@ jobs:
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # See warning above.
         run: julia --project=docs/ docs/make.jl
 ```
 

diff --git a/src/deployconfig.jl b/src/deployconfig.jl
@@ -189,11 +189,6 @@ Implementation of `DeployConfig` for deploying from GitHub Actions.
 The following environment variables influences the build
 when using the `GitHubActions` configuration:
 
- - `DOCUMENTER_KEY`: must contain the Base64-encoded SSH private key for the repository.
-   This variable should be set in the GitHub Actions configuration file using a repository
-   secret, see the documentation for
-   [secret environment variables](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables).
-
  - `GITHUB_EVENT_NAME`: must be set to `push`.
    This avoids deployment on pull request builds.
 
@@ -202,8 +197,22 @@ when using the `GitHubActions` configuration:
  - `GITHUB_REF`: must match the `devbranch` keyword to [`deploydocs`](@ref), alternatively
    correspond to a git tag.
 
+ - `GITHUB_TOKEN`: used for authentication with GitHub, see
+   [GitHub docs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token)
+   for how to set it up.
+   !!! warning
+       When using `GITHUB_TOKEN`, the website served to the user does not get rebuilt,
+       making it look like the documentation build did not succeed.
+       See [issue #1177](https://github.com/JuliaDocs/Documenter.jl/issues/1177)
+       for more information. Due to this Documenter currently also supports pushing
+       with SSH deploy keys from GitHub Actions, but this may change in the future
+       without prior notice. It is therefore recommended to set both `DOCUMENTER_KEY`
+       and `GITHUB_TOKEN` as secret environment variables.
+       See [Authentication: SSH Deploy Keys](@ref) for how to create and set up the
+       ssh deploy key.
+
 The `GITHUB_*` variables are set automatically on GitHub Actions, see the
-[documentation](https://help.github.com/en/articles/virtual-environments-for-github-actions#default-environment-variables).
+[documentation](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables#default-environment-variables).
 """
 struct GitHubActions <: DeployConfig
     github_repository::String
@@ -274,15 +283,19 @@ function deploy_folder(cfg::GitHubActions; repo, devbranch, push_preview, devurl
     actor_ok = haskey(ENV, "GITHUB_ACTOR")
     all_ok &= actor_ok
     println(io, "- $(marker(actor_ok)) ENV[\"GITHUB_ACTOR\"] exists")
-    ## GITHUB_TOKEN should exist (just check here and extract the value later)
-    token_ok = haskey(ENV, "GITHUB_TOKEN")
-    all_ok &= token_ok
-    println(io, "- $(marker(token_ok)) ENV[\"GITHUB_TOKEN\"] exists")
+    # ## GITHUB_TOKEN should exist (just check here and extract the value later)
+    # token_ok = haskey(ENV, "GITHUB_TOKEN")
+    # all_ok &= token_ok
+    # println(io, "- $(marker(token_ok)) ENV[\"GITHUB_TOKEN\"] exists")
+    ## DOCUMENTER_KEY should exist (just check here and extract the value later)
+    key_ok = haskey(ENV, "DOCUMENTER_KEY") || haskey(ENV, "GITHUB_TOKEN")
+    all_ok &= key_ok
+    println(io, "- $(marker(key_ok)) ENV[\"GITHUB_TOKEN\"] (or ENV[\"DOCUMENTER_KEY\"]) exists")
     print(io, "Deploying: $(marker(all_ok))")
     return all_ok ? subfolder : nothing
 end
 
-authentication_method(::GitHubActions) = HTTPS
+authentication_method(::GitHubActions) = haskey(ENV, "DOCUMENTER_KEY") ? SSH : HTTPS
 function authenticated_repo_url(cfg::GitHubActions)
     return "https://$(ENV["GITHUB_ACTOR"]):$(ENV["GITHUB_TOKEN"])@github.com/$(cfg.github_repository).git"
 end

diff --git a/test/deployconfig.jl b/test/deployconfig.jl
@@ -78,6 +78,7 @@ end end
             "GITHUB_REF" => "refs/tags/v1.2.3",
             "GITHUB_ACTOR" => "github-actions",
             "GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
+            "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
         @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
@@ -91,6 +92,7 @@ end end
             "GITHUB_REF" => "refs/tags/not-a-version",
             "GITHUB_ACTOR" => "github-actions",
             "GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
+            "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
         @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
@@ -102,6 +104,7 @@ end end
             "GITHUB_REF" => "refs/heads/master",
             "GITHUB_ACTOR" => "github-actions",
             "GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
+            "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
         @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
@@ -116,6 +119,7 @@ end end
             "GITHUB_REF" => "refs/pull/42/merge",
             "GITHUB_ACTOR" => "github-actions",
             "GITHUB_TOKEN" => "SGVsbG8sIHdvcmxkLg==",
+            "DOCUMENTER_KEY" => nothing,
         ) do
         cfg = Documenter.GitHubActions()
         @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
@@ -135,6 +139,20 @@ end end
         @test Documenter.deploy_folder(cfg; repo="github.com/JuliaDocs/Documenter.jl.git",
                   devbranch="master", devurl="hello-world", push_preview=true) === nothing
     end
+    # Temporary support for SSH push
+    withenv("GITHUB_EVENT_NAME" => "push",
+            "GITHUB_REPOSITORY" => "JuliaDocs/Documenter.jl",
+            "GITHUB_REF" => "refs/tags/v1.2.3",
+            "GITHUB_ACTOR" => "github-actions",
+            "GITHUB_TOKEN" => nothing,
+            "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"
+        @test Documenter.authentication_method(cfg) === Documenter.SSH
+        @test Documenter.documenter_key(cfg) === "SGVsbG8sIHdvcmxkLg=="
+    end
 end end
 
 @testset "Autodetection of deploy system" begin