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.

Adding a new automation rule

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

Navigate to Admin ‣ Automation Rules.
Click on Add Rule and you will see the following form.

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

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.
Choose a Match, which is the pattern you wish to detect in either a Git branch or tag.
- Any version matches all values.
- SemVer versions matches only values that have the SemVer format.
- Custom match matches your own pattern (entered below). If you choose this option, a field Custom match will automatically appear below the drop-down where you can add a regular expression in Python regex format.
Choose a Version type. You can choose between Tag or Branch, denoting Git tag or Git branch.
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).