How to use mkdocs gh-deploy inside a GitHub Action ?

[aahnik]

I had seen some project using it, but could not remember which project.

To use it in a github action, should I need to supply github token or something like that ?

I have written a draft, but I am sure this will fail.

name: Documentation

on:
  push:
    branches:
      - main
    paths:
      - docs
      - README.md


jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - uses: aahnik/setup-pyproject@main
      - name: Build Docs
        run: poetry run mkdocs build -f
      - name: Publish docs
        run: poetry run mkdocs gh-deploy
    
    
    

[Andre601]

This should work, but I can't guarantee it

name​: ​Documentation​

​on​:
  ​push​:
    ​branches​:
      - ​main​
    ​paths​:
      - ​docs​
      - ​README.md​


​jobs​:
  ​docs​:
    ​runs-on​: ​ubuntu-latest​
    ​steps​:
      - ​uses​: ​actions/checkout@v2
      - ​uses​: ​actions/setup-python@v2​
      - name: Install mkdocs
        run: pip install mkdocs
      - ​name​: ​Publish docs​
        ​run​: ​poetry run mkdocs gh-deploy

[Andre601]

This is done through the checkout.

I actually did not know that. Let me try it out. that means the draft I have written in my question should work.

Yes.
I myself use a more special setup on my docs: https://github.com/purrbot-site/Docs

[aahnik]

Run poetry run mkdocs gh-deploy
  poetry run mkdocs gh-deploy
  shell: /usr/bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.9.4/x64
    LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.9.4/x64/lib
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/runner/work/pyproject/pyproject/site 
INFO    -  Documentation built in 0.09 seconds 
WARNING -  Version check skipped: No version specified in previous deployment. 
INFO    -  Copying '/home/runner/work/pyproject/pyproject/site' to 'gh-pages' branch and pushing to GitHub. 
ERROR   -  Failed to deploy to GitHub with error: 
To https://github.com/aahnik/pyproject
 ! [rejected]        gh-pages -> gh-pages (fetch first)
error: failed to push some refs to 'https://github.com/aahnik/pyproject'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
 
Error: Process completed with exit code 1.

Why did this happen ?

[Andre601]

Looks like the gh-pages branch got modified before mkdocs pushed changes...
Iirc can you use the -f flag to force an update...

[aahnik]

Looks like the gh-pages branch got modified before mkdocs pushed changes...

how !? and why ?

I had earlier (long ago) run mkdocs gh-deploy from my machine. So the gh-pages branch already has some commits.

When I run mkdocs gh-deploy again from my computer, it adds new commits without any problem. when the command was run the first time, it created a fresh branch (orphan, and did not have any commits of main)

[aahnik]

[aahnik]

Thanks @Andre601 for help. After little bit of testing, I made it.

name: Documentation

on:
  push:
    branches:
      - main
    paths:
      - "**.md"
      - "mkdocs.yml"
  workflow_dispatch:
  
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v2
      - run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files
      - run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
      - name: Publish docs
        run: mkdocs gh-deploy

See also: #2370 and actions/checkout#479 (comment) and fetch-depth:0

[gregomelo]

For the ones, like me, that still have some trouble. We need to change the Workflow Permissions, as you can see at https://github.com/marketplace/actions/deploy-mkdocs#building-with-github_token.