Work with GitHub
The Istio documentation follows the standard GitHub collaboration flow for Pull Requests (PRs). This well-established collaboration model helps open source projects manage the following types of contributions:
- Add new files to the repository.
- Edit existing files.
- Review the added or modified files.
- Manage multiple release or development branches.
The contribution guides assume you can complete the following tasks:
- Fork the Istio documentation repository.
- Create a branch for your changes.
- Add commits to that branch.
- Open a PR to share your contribution.
Before you begin
To contribute to the Istio documentation, you need to:
Create a GitHub account.
Sign the Contributor License Agreement.
Install Docker on your authoring system to preview and test your changes.
The Istio documentation is published under the Apache 2.0 license.
Perform quick edits
Anyone with a GitHub account who signs the CLA can contribute a quick edit to any page on the Istio website. The process is very simple:
- Visit the page you wish to edit.
preliminaryto the beginning of the URL. For example, to edit
https://istio.io/about, the new URL should be
- Click the pencil icon in the lower right corner.
- Perform your edits on the GitHub UI.
- Submit a Pull Request with your changes.
Active content development takes place using the master branch of the
istio/istio.io repository. On the day of an Istio release, we create a release
branch of master for that release. The following button takes you to the
repository on GitHub:
The Istio documentation repository uses multiple branches to publish
documentation for all Istio releases. Each Istio release has a corresponding
documentation branch. For example, there are branches called
release-1.2 and so forth. These branches were created on the
day of the corresponding release. To view the documentation for a specific
release, see the archive page.
This branching strategy allows us to provide the following Istio online resources:
The public site shows the content from the current release branch.
The preliminary site at
https://preliminary.istio.ioshows the content from the master branch.
The archive site shows the content from all prior release branches.
Given how branching works, if you submit a change into the master branch,
that change won’t appear on
istio.io until the next major Istio release
happens. If your documentation change is relevant to the current Istio release,
then it’s probably worth also applying your change to the current release branch.
You can do this easily and automatically by using the special cherry-pick labels
on your documentation PR. For example, if you introduce a correction in a PR to
the master branch, you can apply the
cherrypick/release-1.4 label in order to
merge this change to the
When your initial PR is merged, automation creates a new PR in the release
branch which includes your changes. You may need to add a comment to the PR
@googlebot I consent in order to satisfy the
CLA bot that we
On rare occasions, automatic cherry picks don’t work. When that happens, the automation leaves a note in the original PR indicating it failed. When that happens, you must manually create the cherry pick and deal with the merge issues that prevented the process from working automatically.
Note that we only ever cherry pick changes into the current release branch, and never to older branches. Older branches are considered to be archived and generally no longer receive any changes.
Istio community roles
Depending on your contributions and responsibilities, there are several roles you can assume.
Visit our role summary page to learn about the roles, the related requirements and responsibilities, and the privileges associated with the roles.
Visit our community page to learn more about the Istio community in general.