istio.io: how the documentation site is versioned and cut

Three sites from one repository

This repository holds the source code for istio.io and for preliminary.istio.io, and the README shows three sites with their own Netlify deploy badges, istio.io, preliminary.istio.io and archive.istio.io. The primary language of the repository is recorded as HTML, which is a fair description of a documentation site with a Hugo build.

The three are not three copies of the same thing. istio.io is the main site, showing the documentation for the current release of the product. istio.io/archive holds snapshots of the documentation for previous releases, and the README says this is useful for customers still using those older releases. preliminary.istio.io holds the actively updated documentation for the next release.

That third one is the reason the repository is worth reading, because it is the difference between a documentation set that lags the code and one that does not. A user reading preliminary.istio.io is reading the docs for a version that has not shipped, and a user on an old release can find the docs that match what they are running. The cost is three copies of the same mental model for anyone writing the documentation, and the branching scheme below is how that cost is managed.

Navigating between them is a gear menu in the top right of each page, and both the main and the preliminary sites are hosted on Netlify. The licence is Apache-2.0, the default branch is master, the last push was on 2026-10-20, and the repository publishes no GitHub releases, because the deliverable is a website rather than an artefact.

How the three sites get their content

The versioning rules are short, and they explain the whole design.

Documentation changes are primarily committed to the master branch, and changes committed to that branch are automatically reflected on preliminary.istio.io. The content of istio.io is taken from the latest release-XXX branch, and the specific branch that is used is determined by the istio.io Netlify project's configuration.

So there is one editing branch, master, and one switch that decides which branch the production site reads. The Netlify configuration is the switch, which means changing what istio.io serves is a configuration change in Netlify rather than a merge, and that is why the release process ends with a person going to the Netlify project.

The consequence for a writer is a delay. Checking in updates to the master branch will automatically update preliminary.istio.io, and will only be reflected on istio.io the next time a release is created, which can be several weeks in the future.

That sentence is the one that surprises new contributors. The site you edit is not the site most users read, and the gap is measured in weeks. The next section is about how the project closes that gap when a change cannot wait.

The cherrypick label, and the two-branch option

If a change has to appear on istio.io immediately, the README gives two routes.

The manual one is to check the changes into the master branch and to the current release branch, which is named release-<MAJOR>.<MINOR>, such as release-1.7.

The automatic one is preferred, and the README says so. If you submit a pull request to the master branch and annotate it with the cherrypick/release-<MAJOR>.<MINOR> label, then as soon as the pull request is merged into master, it will be merged into the specified release branch.

That is a small piece of automation with a large effect on the contributor's workflow. The manual route means every urgent fix has to be committed twice, which is exactly the kind of duplication that leads to the two copies drifting apart. The label route means the contributor touches one branch and the infrastructure handles the backport, and the label itself carries the target version, so the intent is recorded in the pull request rather than in a person's memory.

It is also the sort of thing that only works if the label is applied exactly. The release branch has to exist and have to be the one the label names, and a mistyped version would quietly send the change to a branch that is not being served.

Cutting a release is a script, and it is careful about permissions

The major and minor release procedure has two halves, one for the reference documentation and one for the branch cutting.

The first is a make target. Run make prepare-1.7.0, and that is it, which will grab the latest reference docs from the new Istio source branch into the content/en/docs/reference folder. So the API reference for a new version is pulled from the product repository rather than written by hand, and the make target is the only command involved.

The second is scripts/create_minor_version.sh, which automates the branch cutting process of the documentation. The script will archive the previous minor version of the documentation, create a new branch for the new minor version, create a pull request for master to add the archived documentation and to bump to the next minor version, and create a pull request for the release branch to add the archived documentation.

The README is explicit that this script replaces the old process where an admin needed to commit directly to branches, and that the runner of the script must have enough permissions to create a release branch, while noting that this should be doable for anyone on the docs team, and that the process parallels the branch cutting done by the release managers for minor versions in the other repositories.

The requirements are specific, and the second one is the kind of gotcha that costs an afternoon. The GitHub CLI tool, gh, has to be installed and authenticated, and because of a limitation in the gh tool's pull request creation ability, the forked repository must be created by a user and not by an organization, with a link to the issue. And GNU tools are needed, so on OS X you will have to install at least gnu-sed and have sed linked to that version of the utility.

The dry run, the staging deploy and the publish trigger

The release steps are written as a numbered sequence, and the first one is a rehearsal.

Do a dry run before the official release to ensure everything is working as expected, by specifying DRY_RUN=1 on the command line. The example given is a dry run with FORKED_GIT_SOURCE set to a personal fork and the version as the argument. This will do all the work in a /tmp directory, or in TMP_DIR if you set it, and will not push any changes to the repositories.

On the day of the .0 release, the docs team runs the same command but leaves off the DRY_RUN environment variable, and that is the live publishing.

Then the deployment. Go to the istio.io project on Netlify and set the staging environment to the new release branch and deploy, then open istio-staging.netlify.app and verify that the new release branch is being used and that the documentation looks correct.

Then the hand-off. The release managers should, at this point, merge the publish trigger pull request in the release-builder repository. Once the release is published, or very close to being completed, the docs working group should migrate the istio.io Netlify deployment to use this new release branch.

And then the search index, the Google Custom Search Engine, with steps that the excerpt cuts off.

Read as a whole, the process is a sensible division of labour between a script that can do the mechanical work safely in a temporary directory, a staging deployment that a person can look at, and a trigger in another repository that the release managers control. The one thing the process does not automate is the reading of the staged site, and that is the part a documentation change most needs.

A Hugo site with Go tooling and a shared-files policy

The top-level listing shows what kind of repository this is, and a few entries are worth pointing out.

There is hugo.toml, so the site is a Hugo project, with content/ holding the pages, layouts/ the templates, archetypes/ the scaffolding for new content, and i18n/ the translations. The .spelling file is a word list for the spell checker, and mdl.rb is a markdown lint configuration, with a shellcheckrc for the shell scripts. There is a netlify/ directory and a netlify.toml for the hosting configuration, and a data/ directory for site data.

There is also a Go module, with the module path istio.io/istio.io and Go 1.27.0 in the go.mod. The direct dependencies are the Istio repository itself at a pseudo version, the Kubernetes client libraries, and a diff library, and the indirect list is long, including a CEL expression library, a gettext implementation, a Unicode segmentation library and the CNCF xDS library. That dependency set tells you the site has Go components that talk to the Istio API and the xDS protocol, which is how the release tooling and the search integration work.

The Makefile deserves its own note, because of the warning at the top of it. It says do not edit, this file is probably a copy, and that the original version is located in the istio/common-files repository, with the instruction to make the change there and then run make update-common. So the build files are shared across the Istio repositories and pulled in, which is why Makefile.core.mk and Makefile.overrides.mk exist alongside it, and why the Makefile allows optional per-repository overrides through the overrides file.

The build can also run in a container. Setting BUILD_WITH_CONTAINER to 1 means the only dependencies are make and docker, and if you would rather build with a local toolchain you will need to figure out the tools you need in your environment. There is a shell target for a container shell, and a .devcontainer/ directory for editor support.

How to contribute, and what state the project is in

The README points in three directions for a new contributor. The main Istio README file explains the overall project and how to get in touch, the Istio contribution guidelines cover how to contribute to any of the components, and the creating and editing pages guide is where the mechanics of writing for this site live.

The repository's own files fill in the rest of the picture. CONTRIBUTING.md is there, and so are SUPPORT.md and BUGS-AND-FEATURE-REQUESTS.md, which is where a reader goes when something is wrong with the documentation rather than with the product. CODEOWNERS says who reviews which paths, and CUSTOM_PAGES.md documents the extension point for pages that are not ordinary documentation.

The two files named for languages, I18N-AGENTS-ES.md and I18N-AGENTS-UK.md, are a neat touch. The site is translated, and those files are instructions for an assistant or a contributor working on the Spanish and Ukrainian translations, which is a way of encoding the translation conventions where the people doing the translating will look for them.

On the state of the work, the numbers are simple. The last push was on 2026-10-20, the default branch is master, the repository is not archived, and it publishes no releases. The site is the artefact, it is built continuously on Netlify, and the versioning story is entirely about which branch each of the three sites reads.

Editorial conclusion

Adopt the branching scheme if you are writing Istio documentation, because the master branch, the release branches and the archive are three separate audiences and the labels and scripts in the README are how a change reaches each of them. Do not copy the process into a smaller project without reading the whole thing, because the machinery assumes a docs team, a release manager and a working Netlify staging site. Before you submit a change, read the creating and editing pages guide linked from the README, and if your fix has to appear on the current release site immediately, use the cherrypick label rather than committing to two branches by hand, since the infrastructure does that merge for you.

Frequently asked questions

Official sources

1. Issues
2. istio/istio.io on GitHub
3. License: Apache-2.0
4. Project website
5. README