A github action to ensure chart READMEs are up to date

[max-rocket-internet]

It would be awesome to have a Github Action that will ensure people update chart READMEs on every PR 😃

[max-rocket-internet]

Just an update to this, for our helm charts repo we created a Github action like this: https://github.com/deliveryhero/helm-charts/blob/master/.github/workflows/helm-docs.yml

This ensures all PRs have the chart READMEs updated.

You can update them like this:

docker run --rm -v "$PWD:/helm-docs" jnorwood/helm-docs:latest --template-file=../../ci/README.md.gotmpl

[norwoodj]

Hey @max-rocket-internet would love to do this when I get time. Feel free to submit a PR

[cabrinha]

It'd be nice if this were a published GitHub Action that we could use via the Marketplace.

[TheQueenIsDead]

Hola, I came across this recently while wondering if there was a GitHub action, I was hoping for much the same thing, that a step would fail if the docs were not up to date.

I came up with a solution quite like @max-rocket-internet 's solution, but it relies a little less on bash or files in a repository. For future punters like myself, feel free to make use of it if it helps!

TLDR

      - name: "MD5"
        id: md5
        run: md5sum ./charts/**/README.md ./library/**/README.md > sum

      - name: "Generate Docs"
        uses: docker://jnorwood/helm-docs:latest

      - name: "MD5 Check"
        run: md5sum -c sum

Wait, what is that YAML doing? 🤔

A quick breakdown for nerds, we generate an MD5 sum of each of the files, and save that as a file in the working directory. It looks like this:

$ md5sum ./charts/**/README.md ./library/**/README.md
fe2d28d7dae4a86745f461cc71831b3b  ./charts/app-chart/README.md
03c0e0624c723316b67764858f6a9992  ./charts/php-chart/README.md
d26c945ead7f63b4c8943228c1a915cf  ./charts/service-chart/README.md
7276b329c5372ad38720b5293cebec7d  ./library/common-library/README.md

Then we actually have the cool ability to use published docker containers as the step in GitHub actions without having to run the entire job in the container. This can be achieved via the uses: keyword and the docker:// extension. The default entrypoint of the container is helm docs, and the default behaviour of the bin is to generate docs.

Thank you @norwoodj for setting up the docker side of things so nicely :pray:

Lastly, after the docs have been generated (They persist, as the step is ran with the CWD mounted in, persisting README changes), we use the previously generated sum file to re-check if the files have changed.

If the readme has been updated, then the step will fail as the md5 is different. Else it will pass :-)

Here's an example of that output:

Run md5sum -c sum
  md5sum -c sum
  shell: sh -e {0}
./charts/app-chart/README.md: OK
./charts/php-chart/README.md: OK
./charts/service-chart/README.md: OK
./library/common-library/README.md: FAILED
md5sum: WARNING: 1 of 4 computed checksums did NOT match
Error: Process completed with exit code 1.

[max-rocket-internet]

Very nice @TheQueenIsDead! Thanks for sharing.

it relies a little less on bash or files in a repository

I like your clean approach but one of the main reasons I went with the script as it will print the diff to show clearly to the user what is expected/required to get the check to pass. We get a lot of PRs from random people and it can be hard for a new user to work out exactly what is required.

[TheQueenIsDead]

That's a great reason to do so! I like the clear use of emojis to highlight success/failure too. We've got a few repositories running off of a central pipeline and try stay away from files where possible, but I'm sure that script could be added to a runs: |​ action if anyone was adamant.

Diffs is a great tool, I'm happy to have stumbled across this Github issue, hope that everyone that might come down here can find something that fits their workflow perfectly 💯

---

From: Max Williams @.> Sent: Tuesday, 23 August 2022 9:18 pm To: norwoodj/helm-docs @.> Cc: TheQueenIsDead @.>; Mention @.> Subject: Re: [norwoodj/helm-docs] A github action to ensure chart READMEs are up to date (#52)

Very nice @TheQueenIsDeadhttps://github.com/TheQueenIsDead! Thanks for sharing.

it relies a little less on bash or files in a repository

I like your clean approach but one of the main reasons I went with the script as it will print the diff to show clearly to the user what is expected/required to get the check to pass. We get a lot of PRs from random people and it can be hard for a new user to work out exactly what is required.

— Reply to this email directly, view it on GitHubhttps://github.com/norwoodj/helm-docs/issues/52#issuecomment-1223794471, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AHKIW6AEQGSI24LGSUMY2ITV2SJQHANCNFSM4P4YVG3Q. You are receiving this because you were mentioned.Message ID: @.***>

[GMartinez-Sisti]

We're using a similar approach that show diffs and also missing files. This is the cleanest we could create:

name: Docs check

on: pull_request

defaults:
  run:
    shell: bash

jobs:
  docs-check:
    runs-on: [self-hosted, Linux, X64]
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - name: Ensure documentation is updated
        uses: docker://jnorwood/helm-docs:latest

      - name: Check for changes
        run: |
          if git diff --exit-code; then
            echo -e "\n####### Git is clean\n"
          else
            git status
            echo -e "\n####### Git changes detected! Check and commit changes !!!\n"
            exit 1
          fi

• Using actions/checkout@v3 with ref: ${{ github.event.pull_request.head.sha }} is required to be able to use git commands, otherwise a commit merge is created on top of the tree and that breaks the functionality
• git diff --exit-code fails if there are git changes and shows the diffs on tracked files
• git status shows the changed files and untracked files that were created by the previous step