This is a tutorial about how to publish your Helm charts repository using GitHub pages.
It is also a working example that you can test with Helm, or fork to create your own Helm charts repository using GitHub Pages.
If you are viewing this from the GitHub repository information page, check how it is seen as a website at:
Using GitHub pages, you publish a Jekyll generated web page from the markdown files on your repository.
Going into settings for the repo, at the bottom of the first settings page you have three options for what to expose as a public website:
- None (no website, default value)
- Expose your main master branch
- Expose another designated branch
- Expose content from a docs directory on your repository (you can't choose a different directory name or path)
The last option is best for keeping some content accesible from the main repository URL, and at the same time make clear where additional files are.
In this exaple we chose the first one, so when we update the root readme.md
, the same file gets exposed to the website and the repository page on GitHub.
Take into consideration that if your repository is private or internal to a team, the website will be enabled publicly, and all the contents from the branch or docs folder can be accessed.
The URL will be in the form of:
<github_username>.github.io/<repo_name>
If your repository name is <github_username>.github.io
, the URL will not use the repo name, and just be shown as:
<github_username>.github.io
On repository settings, in adition to set up what to expose to the public web, you can:
- Choose an image that will be used when sharing the site in social media posts.
- Enforce HTTPS the public URLs with a certificate issued by github.com
- Add your own custom domain
- Choose a template for pages generated from markdown to HTML and CSS by Jekyll
You can use your own HTML and CSS files, placing an index.html
file on folders to be shown by default, or use markdown files that GitHub Jekyll enging transforms to HTML using templates.
If you want to use markdown, the default file that will be shown on each directory has to be named index.md
, unless it's on the root directory, where readme.md
will be also used.
When you apply or change a theme from settings, a _config.yml
file will be commited to the exposed directory/branch, where you can set aditional settings for the Jekyll template (see references).
To store charts, you have to package them and move to a subdirectory of your public website one, for example, packages
.
Inside that folder we will place packaged charts tgz
format (don't do it yourself, use the Helm package
command).
We will create a index.yaml
file to list the charts, as we explain in the following steps:
# Prepare your packaged chart
# "falco" package folder not included in this demo
cd packages
helm package ../charts/falco
#Update index.yml searching all first level subfolders for possible packaged charts
cd ..
helm repo index . --url https://<github_username>.github.io/<repo_name>
How we used in this repo:
helm repo index . --url https://vicenteherrera.github.io/github-pages-helm-charts
To add this repository to deploy charts from it:
helm repo add my-repo https://vicenteherrera.github.io/github-pages-helm-charts
helm repo update
helm search repo github-pages-helm-charts
Visit:
You should see the content from:
If you visit:
You should see the contents of index.yaml file:
If you want to export the charts you previously hosted on github.com/helm/charts with all their commits history to a new repository, but without any other chart's history in it, follow these steps.
# 1. Create a new empty GitHub empty repository, without any commits in it.
# 2. Clone helm/charts repository
git clone [email protected]:helm/charts.git
cd charts
# 3. Upload selected folder history to master branch of new repository
git subtree push --prefix=charts/<your_chart_folder> <destiny_repo_url> master
After this, your chart content and all its history will be available in master branch of the newly created GitHub repository (you can move it to wherever you want).
You will have to download all packaged chart for each version, and move it to the packages
folder.
# List all versions of your chart
helm search repo stable/<your_chart> --versions
# Download a specific packaged chart version
helm pull stable/<your_chart> --version <ver_number>
- Helm chart on GitHub pages
- GitHub pages
- Jekyll themes for GitHub pages
- Customizing Cayman Jekyll theme
- CircleCI to generate Helm chart on GitHub pages
- GitHub action to generate Helm chart on GitHub Pages
- GitHub action from Helm to automate releasing and publishing charts based on Chart Releaser
- Helm tool Chart Releaser
Done by Vicente Herrera for sysdig.com