How to manage versions automatically

In this guide, we show you how to define rules to automate creation of new versions on Read the Docs, using your Git repository’s version logic. Automating your versioning on Read the Docs means you only have to handle your versioning logic in Git.

See also

Versioned documentation

Learn more about versioning of documentation in general.

Automation rules

Reference for all different rules and actions possible with automation.

Adding a new automation rule

First you need to go to the automation rule creation page:

  1. Navigate to Admin ‣ Automation Rules.

  2. Click on Add Rule and you will see the following form.

Screenshot of the "Add Rule" form

In the Automation Rule form, you need to fill in 4 fields:

  1. Enter a Description that you can refer to later. For example, entering “Create new stable version” is a good title, as it explains the intention of the rule.

  2. Choose a Match, which is the pattern you wish to detect in either a Git branch or tag.

  3. Choose a Version type. You can choose between Tag or Branch, denoting Git tag or Git branch.

  4. Finally, choose the Action:

Now your rule is ready and you can press Save. The rule takes effect immediately when a new version is created, but does not apply to old versions.

Tip

Examples of common usage

See the list of examples for rules that are commonly used.

Want to test if your rule works?

If you are using Git in order to create new versions, create a Git tag or branch that matches the rule and check if your automation action is triggered. After the experiment, you can delete both from Git and Read the Docs.

Ordering your rules

The order your rules are listed in Admin ‣ Automation Rules matters. Each action will be performed in that order, so earlier rules have a higher priority.

You can change the order using the up and down arrow buttons.

Note

New rules are added at the start of the list (i.e. they have the highest priority).