Automation rules allow project maintainers to automate actions on new branches and tags on repositories.
- Go to your project dashboard
- Click :guilabel:`Admin` > :guilabel:`Automation Rules`
- Click on :guilabel:`Add Rule`
- Fill in the fields
- Click :guilabel:`Save`
When a new tag or branch is pushed to your repository, Read the Docs creates a new version.
All 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 rules, and all matching actions will be performed on the version.
Automation rules support several 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.
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.
When a 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 :ref:`versions:Version States`.
Make version public: Sets the version's privacy level to public. See :ref:`versions:privacy levels`.
Make version private: Sets the version's privacy level to private. See :ref:`versions:privacy levels`.
Set version as default: Sets the version as default, i.e. the version of your project that / redirects to. See more in :ref:`automatic-redirects:Root URL`. It also activates and builds the version.
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.
Note
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.
Note
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 :doc:`versions`.
The order your rules are listed in :guilabel:`Admin` > :guilabel:`Automation Rules` matters. Each action will be performed in that order, so first rules have a higher priority.
You can change the order using the up and down arrow buttons.
Note
New rules are added at the end (lower priority).
- Match:
Any version
- Version type:
Tag
- Action:
Activate version
- Custom match:
^1\.\d+$
- Version type:
Branch
- Action:
Activate version
- Match:
Any version
- Version type:
Branch
- Action:
Delete version
- Custom match:
-(stable|release)$
- Version type:
Tag
- Action:
Set version as default
Note
You can also create two rules:
one to match -stable
and other to match -release
.
- Custom match:
^[vV]
- Version type:
Tag
- Action:
Activate version
- Custom match:
^[vV]
- Version type:
Branch
- Action:
Activate version
- Custom match:
.*(?<!-nightly)$
- Version type:
Tag
- Action:
Activate version