mkdocs auto deploy doesnot work.

[vyasakhilesh]

While running below command from the host machine

sh run.sh make update_docs

Getting this error

mkdocs gh-deploy --config-file ../../mkdocs.yaml
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /work/site
WARNING  -  A relative path to 'odk-workflows/ManageAutomatedTest.md' is included in the 'nav' configuration,
            which is not found in the documentation files
WARNING  -  Documentation file 'odk-workflows/index.md' contains a link to
            'odk-workflows/ManageAutomatedTest.md' which is not found in the documentation files.
INFO     -  Documentation built in 0.35 seconds
INFO     -  Copying '/work/site' to 'gh-pages' branch and pushing to GitHub.
The authenticity of host 'github.com (::ffff:140.82.121.4)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'github.com' (ED25519) to the list of known hosts.
Connection reset by 140.82.121.4 port 22
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.10/dist-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.10/dist-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.10/dist-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.10/dist-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.10/dist-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.10/dist-packages/mkdocs/__main__.py", line 280, in gh_deploy_command
    gh_deploy.gh_deploy(
  File "/usr/local/lib/python3.10/dist-packages/mkdocs/commands/gh_deploy.py", line 127, in gh_deploy
    ghp_import.ghp_import(
  File "/usr/local/lib/python3.10/dist-packages/ghp_import.py", line 285, in ghp_import
    git.check_call('push', opts['remote'], opts['branch'])
  File "/usr/local/lib/python3.10/dist-packages/ghp_import.py", line 119, in check_call
    sp.check_call(['git'] + list(args), **kwargs)
  File "/usr/lib/python3.10/subprocess.py", line 369, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['git', 'push', 'origin', 'gh-pages']' returned non-zero exit status 128.
make: *** [Makefile:705: update_docs] Error 1

[matentzn]

Hey @vyasakhilesh -

I just tested this on two of my repos, and it works OK.

Note that in order to run this, you need to have at least write rights on the repo in question (you need to be able update branches). Can you double check your permissions?

Also, you may have to generate a GitHub token to use as a password for this process.

[vyasakhilesh]

Thanks @matentzn , I was trying to do it using ssh-keys .. so do you need to include the token in the origin URL? Or simply in .github/token.txt file ? Does it ask for a username and password when update_docs tries to push code in the remote repo if you add in token.txt?

[matentzn]

Yes, it does ask me for username and password.. If you want to get this working with token.txt: @gouttegd I never tried this, but is there anything @vyasakhilesh needs to do specifically?

[gouttegd]

I don’t think it would be possible to use a GitHub token for this. From what I can see, mkdocs gh-deploy does not use the GitHub API (either directly or through gh, the GitHub CLI tool). It only uses standard git commands, which have nothing to do with GitHub API and won’t care about a GitHub token.

Standard git commands know how to use a SSH key, but the problem here is that the command is run from within a Docker container, which does not have access to ~/.ssh.

@vyasakhilesh : Is your SSH setup “complicated”? Like, do you use SSH agent with forwarding, or a private key stored on a physical token that you access through GnuPG or similar?

If you have a simple setup (like, a regular SSH key stored in ~/.ssh/id-rsa), then you could try binding your ~/.ssh directory to the /root/.ssh directory within the container. That should be enough to allow git to use your key. You can do that by adding the following to the run.sh.conf file (create that file if you don’t already have one):

ODK_BINDS=~/.ssh:/root/.ssh:ro

[pfabry]

As a workaround, are there known problems with using mkvdocs build instead of mkvdocs gh-deploy and then commit/PR the docs with the rest of the repo?
This way you don't have to authenticate yourself when updating the docs and you're sure that the repo is up to date with the docs.

[matentzn]

@pfabry I did exactly that in the past, no problems at all. I do believe that mkdocs gh-deploy does not really create a commit though, it seems to overwrite the whole branch. At least it seems that way, see https://github.com/obophenotype/upheno/commits/gh-pages

[matentzn]

@vyasakhilesh I am closing this now, but if this continues to be an issue please re-open!