Auto updating the insiders version with an action

[dmundra]

We use poetry to manage installing the insiders repo for our guidebook. I wanted a way to see if dependabot could check if there is a new version of the repo and create a pull request with the update. I found that it is not possible as mentioned here dependabot/dependabot-core#6147.

My solution was to write a custom script that compares the version installed and the version available and then create a pull request with a github action. Here is the script https://github.com/CivicActions/guidebook/blob/master/.config/mkdocs/check-material-insiders-version.sh and the github action https://github.com/CivicActions/guidebook/blob/master/.github/workflows/material-insiders-update.yml.

Question here is could this script be turned into a github action that anyone can add to their repo call it mkdocs-material-bot to provide updates and also handle rebasing like dependabot.

[squidfunk]

I have no experience with poetry, so maybe somebody else can share a workflow. Other than that, this could likely be turned into a GitHub action, but we currently have no bandwidth to do this. If you decide to create one, let us know, we'll link it in the docs! ☺️

[dmundra]

Sounds good. I wondering if I could make a dependabot plugin so I can use its features.

[ydkmlt84]

Is there documentation on the proper/recommended way of updating our fork to include the new changes? Sorry, I know this post is a little old.

[ydkmlt84]

what happened to the publish.yml of the insiders repo?

[squidfunk]

We do not publish documentation for Insiders – all Insiders docs are part of the main documentation.

[ydkmlt84]

I was looking at this part of the Getting Started with Insiders. I see now that the build.yml workflow publishes to GHCR.

https://squidfunk.github.io/mkdocs-material/insiders/getting-started/#:~:text=The%20publish%20workflow4

[squidfunk]

Sorry, you're right, publish.yml carries the logic on building the Docker image. This was consolidated into a unified workflow in #5088, so we need to fix the link.

[squidfunk]

Fixed in 6c796c0

[kamilkrzyskow]

A few months back, I've added a custom workflow which updates the repository daily, on my Insiders fork.

First commit modifies the .github/workflows/build.yml file, I changed the initial lines:

on:
  push:
    branches:
      - masterr
  #pull_request:
  #release:
  #  types:
  #    - published

As long as those lines won't change then there shouldn't be any merge conflicts. (EDIT: Now that I thought about it, the change from master to masterr should be sufficient, as other types of triggers don't apply to forks anyways 😅)

The second commit adds a custom .github/workflows/_custom_auto_update_.yml workflow file, which fetches the changes from upstream and rebases those 2 commits onto the new changes from Insiders, then a force push is required, because the flow of the commit tree has been broken:

name: Auto update

on:
  schedule:
    - cron: '0 20 * * *' # Runs every day at 8 PM UTC (9 PM Polish time during standard time)
  workflow_dispatch: # Allows manual triggering of the workflow

env:
  PRIVATE_ACCESS: ${{ secrets.PRIVATE_ACCESS }}

jobs:
  auto-update:
    runs-on: ubuntu-latest

    steps:
    
      - name: Clone repository
        # Just to be safe get some commit history we need it to rebase.
        # Perhaps actions/checkout is enough, but it didn't work, back to the basics.
        run: git clone --depth 10 https://$GITHUB_ACTOR:[email protected]/<MY_USERNAME>/mkdocs-material-insiders.git .
        
      - name: Set credentials
        run: |
          git config user.name "<MY_NAME>"
          git config user.email "<MY_EMAIL>"

      - name: Add mkdocs-material upstream remote
        run: git remote add upstream https://$GITHUB_ACTOR:[email protected]/squidfunk/mkdocs-material-insiders.git
        
      - name: Fetch upstream remote
        # Fetch only 200 commits as daily updates should not need more.
        # We're rebasing the commits, so we don't need to keep track all commits.
        run: git fetch --depth 200 upstream

      - name: Rename current master with changes to custom-master
        run: git branch -m master custom-master

      - name: Git change branch to upstream master
        run: git checkout --track upstream/master
        
      - name: Show git status of the upstream master
        run: |
          git status --verbose
          git log -n 10 --pretty=one
      
      - name: Switch to the branch with the custom changes
        run: git checkout custom-master

      - name: Rebase custom changes onto clean master
        run: git rebase master
        
      - name: Force push changes of the rebase
        run: git push origin custom-master:master --force

[santaimpersonator]

For general use cases, we don't even fork the mkdocs-material-insiders repo anymore. You can just follow their updated instructions here, where the workflow automatically uses the latest version of mkdocs-material-insiders to build your documentation.

Current workflow, as shown in doc (in case, it's updated):

name: ci
on:
  push:
    branches:
      - master
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    if: github.event.repository.fork == false
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache 
          restore-keys: |
            mkdocs-material-
      - run: apt-get install pngquant 
      - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
      - run: mkdocs gh-deploy --force
env:
  GH_TOKEN: ${{ secrets.GH_TOKEN }}

Note

Remember to set the GH_TOKEN repository secret to the value of your personal access token when deploying Insiders, which can be done using GitHub secrets.

---

You could probably change you workflow/shell script to just clone the latest release of mkdocs-material-insiders, instead of creating a pull request every time:

      - name: Clone MkDocs-Material Insiders
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        run: git clone https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git