Automation rules
Automation rules allow project maintainers to automate actions on new branches and tags in Git repositories. If you are familiar with GitOps, this might seem familiar. The goal of automation rules is to be able to control versioning through your Git repository and avoid duplicating these efforts on Read the Docs.
See also
- How to manage versions automatically
A practical guide to managing automated versioning of your documentation.
- Versions
General explanation of how versioning works on Read the Docs
How automation rules work
When a new tag or branch is pushed to your repository, Read the Docs receives a webhook. We then create a new Read the Docs version that matches your new Git tag or branch.
All automation rules are evaluated for this version, in the order they are listed. If the version matches the version type and the pattern in the rule, the specified action is performed on that version.
Note
Versions can match multiple automation rules, and all matching actions will be performed on the version.
Matching a version in Git
We have a couple predefined ways to match against versions that are created, and you can also define your own.
Predefined matches
Automation rules support two predefined version matches:
Any version: All new versions will match the rule.
SemVer versions: All new versions that follow semantic versioning will match the rule.
Custom matches
If none of the above predefined matches meet your use case, you can use a Custom match.
The custom match should be a valid Python regular expression. Each new version will be tested against this regular expression.
Actions for versions
When an automation rule matches a new version, the specified action is performed on that version. Currently, the following actions are available:
- Activate version
Activates and builds the version.
- Hide version
Hides the version. If the version is not active, activates it and builds the version. See Version states.
- Make version public
Sets the version’s privacy level to public. See Privacy levels.
- Make version private
Sets the version’s privacy level to private. See Privacy levels.
- Set version as default
Sets the version as the default version. It also activates and builds the version. See Root URL redirect at /.
- Delete version
When a branch or tag is deleted from your repository, Read the Docs will delete it only if isn’t active. This action allows you to delete active versions when a branch or tag is deleted from your repository.
There are a couple caveats to these rules that are useful:
The default version isn’t deleted even if it matches a rule. You can use the
Set version as default
action to change the default version before deleting the current one.If your versions follow PEP 440, Read the Docs activates and builds the version if it’s greater than the current stable version. The stable version is also automatically updated at the same time. See more in Versions.
Order
When a new Read the Docs version is created, all rules with a successful match will have their action triggered, in the order they appear on the Automation Rules page.
Examples
Activate only new branches that belong to the 1.x
release
Custom match:
^1\.\d+$
Version type:
Branch
Action:
Activate version
Delete an active version when a branch is deleted
Match:
Any version
Version type:
Branch
Action:
Delete version