GitHub Pages build not triggered with GITHUB_TOKEN

[maxmouchet]

According to #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?

[CiaranOMara]

I've got a test deployment at https://ciaranomara.github.io/GenomicFeatures.jl/dev/ and https://ciaranomara.github.io/GenomicFeatures.jl/previews/PR11/. The repository is https://github.com/CiaranOMara/GenomicFeatures.jl.

These redundant examples no longer exist as I cleaned out my repository.

[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 tkf/BenchmarkCI.jl#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 JuliaRegistries/CompatHelper.jl#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.

[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.