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.

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 Versioned documentation.

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 all new tags

Match: Any version
Version type: Tag
Action: Activate version

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

Set as default new tags that have the `-stable` or `-release` suffix

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.

Activate all new tags and branches that start with `v` or `V`

Custom match: ^[vV]
Version type: Tag
Action: Activate version

Custom match: ^[vV]
Version type: Branch
Action: Activate version

Activate all new tags that don’t contain the `-nightly` suffix

Custom match: .*(?<!-nightly)$
Version type: Tag
Action: Activate version