Documenter.jl: GitHub Pages build not triggered with GITHUB_TOKEN

[maxmouchet]

According to https://github.com/JuliaDocs/Documenter.jl/pull/1165 GITHUB_TOKENis sufficient for Documenter to push to gh-pages.

However it seems that this token is not allowed to trigger pages builds [1]:

The GITHUB_TOKEN that is provided as a part of GitHub Actions doesn't have authorization to create any successive events, such as GitHub Pages builds. So while you can push to the gh-pages branch using the GITHUB_TOKEN, it won't spawn a GitHub Pages build. You'll need to create a personal access token and supply it to your GitHub Action as a secret.

Hence, docs. are correctly pushed, but GitHub Pages are never updated.
Is there any workaround ?

I tried to add a manual build trigger [2] in my workflow:

- name: Build and deploy
  env:
    DOCUMENTER_DEBUG: true
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        julia --project=docs/ docs/make.jl
        curl -u maxmouchet:${GITHUB_TOKEN} -X POST https://api.github.com/repositories/164427411/pages/builds -H "Accept: application/vnd.github.mister-fantastic-preview+json"

but the GitHub API returns the following error:

{
  "message": "Resource not accessible by integration",
  "documentation_url": "https://developer.github.com/v3/repos/pages/#request-a-page-build"
}

[1] https://github.community/t5/GitHub-Actions/Github-action-not-triggering-gh-pages-upon-push/td-p/26869
[2] https://stackoverflow.com/a/54088985

[maxmouchet]

Of course, one workaround is to "create a personal access token and supply it to your GitHub Action as a secret", but the documentation should at-least specify that :-)

[fredrikekre]

Yea, I thought we already had an issue about this. I had hoped GH would have fixed this but I guess not.

[fredrikekre]

You can use a SSH deploy key now: #1183

[CiaranOMara]

The GITHUB_TOKEN seem to work for me when I have a .nojykell present in the gh-pages branch.

[fredrikekre]

Do you have an example?

[fredrikekre]

But it didnt build; https://github.com/CiaranOMara/GenomicFeatures.jl/commits/gh-pages

[CiaranOMara]

I generated a few more pull requests and it turns out that I spoke too soon. The act of pushing something (.nojykell) to the gh-pages branch outside of the workflow triggered a GitHub pages build.

[fredrikekre]

Yea, because then you are the commiter, not github-actions.

[aminya]

This feature will remove the need for a separate SSH key.

[lindnemi]

@aminya which feature? how do i get it?

[fredrikekre]

There is no feature. This is up to GitHub.

[tkf]

Maybe it is worth noting that another workaround is to use a custom token instead of GITHUB_TOKEN. Here is an example that works without DOCUMENTER_KEY https://github.com/tkf/BenchmarkCI.jl/pull/24.
This is slightly handier if you need to setup other GitHub Actions that require a custom token such as CompatHelper.jl combined with CI ran on GitHub Actions https://github.com/bcbi/CompatHelper.jl/issues/176.

[bramtayl]

Hi. So I'm trying to update OnlinePackage.jl to use github actions instead of travis. I'm kinda at a loss. I'm to the point where I can get a public and private SSH key, but according to the docs at https://developer.github.com/v3/actions/secrets/#create-or-update-a-secret-for-a-repository, to upload the private SSH key as a secret, I have to download another key from github, encode the private key using sodium, and then upload again? Sodium.jl seems very out of date and I have no where near the technical knowledge to be able to resurrect it. What are my options?

[aminya]

You can use this to make automatic deployment work:

# ]add DocumenterTools
using YourPackage, DocumenterTools
DocumenterTools.genkeys(YourPackage)

Add the public key to https://github.com/Username/YourPackage.jl/settings/keys
Add the private key to https://github.com/Username/YourPackage.jl/settings/secrets

We should reword the doc to make it simpler.

• Now it is written in a way that makes things hard to understand.
• the documentation should prefer GithubActions over Travis, and make Travis a separate package.
• I added Windows support for DocumenterTools. So the sections that describe how to use Puttygen are not needed any more.

[kleinschmidt]

The downside of using a custom secret (like the DOCUMENTER_TOKEN approach) is that those secrets aren't passed to workflows triggered by PRs from forks (quite sensibly, since you could hijack secrets that way). So this means that doc previews from PRs only work for PRs that are initiated from the repository itself. I'm assuming that the docs will still build and deploy normally when the PR is merged, but it would be nice to be able to take advantage of the preview feature. Still, I get that this is up to github so...

[kleinschmidt]

Actually, now that I've thought about it for five more minutes, that won't work, since to view the preview you still need gh-pages build to trigger.

[mortenpi]

The downside of using a custom secret (like the DOCUMENTER_TOKEN approach) is that those secrets aren't passed to workflows triggered by PRs from forks (quite sensibly, since you could hijack secrets that way).

For the same reason that custom secrets are not passed to workflows from forks, GitHub Tokens have only read permissions in that situation. So you can't make doc previews on forks work with them.

Except if you would try to push to the gh-pages of the _forked_ repo..? Would the token have write access to that?

[bramtayl]

Ok y'all. Progress:

• I used binary builder to build libsodium so you can now use it with using libsodium_jll
• I used ccall on specific functions from libsodium to encrypt the private key
• I updated OnlinePackage to submit the private SSH key as a secret encoded with libsodium via the GitHub API
• I used OnlinePackage to update the SSH keys of JuliennedArrays

And...

The docs for JuliennedArrays failed to build.

Can I express general unhappiness about how difficult this is?

[SaschaMann]

Can I express general unhappiness about how difficult this is?

Unless you want to set the secret programmatically via the API, you don't need to use libsodium. You can add it in the settings menu on GitHub: https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets

[bramtayl]

you want to set the secret programmatically via the API

Well the whole point of OnlinePackage was to do this programmatically so that no one else besides me ever had to worry about SSH keys again

[bramtayl]

I released OnlinePackage 0.2. It will automatically generate SSH keys and upload them to your packages for you.

[lindnemi]

Since a few days my pages build are triggered when using GITHUB_TOKEN, so i guess GitHub has fixed the issue?

[bramtayl]

Just tested it out and GITHUB_TOKEN is working for me tooo!!!!!

[garborg]

I just tried this with a repo fresh of the PkgTemplates.jl (0.7-dev) presses, and docs wouldn't build unless I followed up having my user commit a no-op commit to the gh-pages branch. Am I misunderstanding the meaning of 'build are triggered when using GITHUB_TOKEN'?

Job:
https://github.com/garborg/MoneyPattern.jl/blob/92f03ad770b16208144df329ef4b2cbba8721bfa/.github/workflows/ci.yml#L29-L44

N.b. this is my first time trying github actions, so if there's any extra setup involved beyond getting jobs running successfully, that may be what I'm missing.

[bramtayl]

The repos I've tried this on already had an existing gh-pages branch

[garborg]

Thanks, @bramtayl. Subsequent actions runs (after a manual push to the gh-pages branch to trigger an initial build) are triggering gh-pages builds for me, too.

[mortenpi]

I can also confirm that (1) it works now if gh-pages already exists, and (2) doesn't work if Documenter has to create gh-pages for you.

For (2), another workaround is to toggle the "Source" option in the GitHub Pages settings of your repository after Documenter has deployed something onto gh-pages.

[bramtayl]

@mortenpi there's an API for changing the source option now

https://developer.github.com/v3/repos/pages/#enable-a-pages-site

If you want I could cook up some code based on the OnlinePackage infrastructure. Not sure what the best venue for it to live in would be.

[marius311]

Is everyone atually in agreement this now works with GITHUB_TOKEN? It seems to just have _not_ worked for me, and this was in a case where I already had a gh-pages branch and it has in the past succesfully built. Is it possible its only sporadically working? I'll test my own stuff more but wanted to ask.

[fredrikekre]

I think it depends on what triggers the build.

[mortenpi]

Closing this as the issue described in the OP has been fixed on GitHub's side.

[rdeits]

The documenter docs still say:

Currently the GitHub Page build is not triggered when the GitHub provided GITHUB_TOKEN is used for authentication. See issue #1177 for more information.

Can that section be deleted now?

[Nosferican]

I think the docs should point out that for gh-pages to be build the commit history must have some commit by a user with admin privileges for the repo. That means that the bot which has only write permissions will not initially trigger the build. That can be fixed by making any commits to the gh-pages branch and then the docs will be build as usual and it can use only the GITHUB_TOKEN.

[knuesel]

When updating the doc, the following warning should also be removed in deployconfig.jl:

function authentication_method(::GitHubActions)
    if haskey(ENV, "DOCUMENTER_KEY")
        return SSH
    else
        @warn "Currently the GitHub Pages build is not triggered when " *
              "using `GITHUB_TOKEN` for authentication. See issue #1177 " *
              "(https://github.com/JuliaDocs/Documenter.jl/issues/1177) " *
              "for more information."
        return HTTPS
    end
end

[knuesel]

I can't reproduce the problem with the gh-pages branch: I just tested with two packages, and in both cases the build was triggered. The steps were:

1. Create empty repo on GitHub
2. Create package skeleton with PkgTemplates
3. Push to GitHub.
   → Here the deploy fails because it defaults on DOCUMENTER_KEY which is defined but empty.
4. Remove DOCUMENTER_KEY from ci.yml and push to GitHub.
   → The deploy succeeds, the gh-pages branch is created.
5. On GitHub, go to settings and enable GitHub Pages with the gh-pages branch created by CI.
   → The pages are published after a while.

Can someone still reproduce the problem? If yes what are the exact steps?

[fredrikekre]

I believe builds from tags generated with GITHUB_TOKEN still does not trigger a gh-pages build.

[knuesel]

There's already a big warning for that though (see https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#GitHub-Actions ). Maybe we can leave this one and just remove the other one.