Automate Helm chart repository publishing with GitHub Actions and Pages

For open source projects, GitHub Pages is a great choice to host Helm repositories. At Weaveworks, for projects like Flux and Flagger we’re using the gh-pages branch to store and serve the packaged charts. After each release we undergo a manual process of packaging and pushing the new chart version to the gh-pages branch.

While experimenting with GitHub Actions I’ve noticed that GitHub creates a secret with a token that can be used to push changes back to the repository.

In order to automate the process of packaging and publishing Helm charts to GitHub pages I’ve made a GitHub action called helm-gh-pages.

This action has the following inputs:

• token The GitHub token with write access to the target repository
• charts_dir The charts directory, defaults to charts
• charts_url The GitHub Pages URL, defaults to https://<OWNER>.github.io/<REPOSITORY>
• owner The GitHub user or org that owns this repository, defaults to the owner in GITHUB_REPOSITORY env var
• repository The GitHub repository, defaults to the GITHUB_REPOSITORY env var
• branch The branch to publish charts, defaults to gh-pages
• helm_version The Helm CLI version, defaults to the latest release

Before using the action make sure your Git repository has a gh-pages branch published on GitHub Pages.

Workflow

Package and push all charts in ./charts dir to gh-pages branch when creating a GitHub release:

name: release
on:
  push:
    tags: '*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Publish Helm charts
        uses: stefanprodan/helm-gh-pages@master
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

Publish the Helm chart located at chart/flux to the gh-pages branch of a different repository:

name: release-chart
on:
  push:
    tags: 'chart.*'

jobs:
  release-chart:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Publish Helm chart
        uses: stefanprodan/helm-gh-pages@master
        with:
          token: ${{ secrets.BOT_TOKEN }}
          charts_dir: chart
          charts_url: https://charts.fluxcd.io
          owner: fluxcd
          repository: charts
          branch: gh-pages

Release process

Assuming your GitHub repository has a Helm chart named app located at charts/app the release procedure could be:

# make changes to chart/app and bump the version in Chart.yaml
> git commit -m "Bump chart version to 1.0.0"
> git push origin master
# release v1.0.0
> git tag v1.0.0
> git push origin v1.0.0

When you push the tag, GitHub will start the workflow and the helm-gh-pages action will do the following:

• checks out the v1.0.0 tag
• validates the chart by running Helm lint
• packages the chart as app-1.0.0.tgz
• checks out the gh-pages branch
• copies the app-1.0.0.tgz in the repo root dir
• updates the Helm repository index using the GitHub pages URL
• commits the chart package and the Helm repository index
• pushed the changes to gh-pages

In couple of seconds GitHub will publish the change to GitHub Pages and your chart v1.0.0 will be available for download.

If you have any suggestion on improving helm-gh-pages please submit an issue or PR on GitHub at stefanprodan/helm-gh-pages.