Automation rules let project maintainers automate actions on new branches and tags pushed to their Git repository: activate a version, hide it, set it as default, delete it on branch deletion, and more. Today we are announcing several new features to automation rules that will make rules more flexible and unlock a long-requested capability: filtering builds based on the contents of a webhook event.

What's new

Match multiple version types in a single rule

Previously, a rule applied to either a tag or a branch. Now a rule can target any combination of tags, branches, and pull requests at the same time. This avoids duplicating the same rule with different version types just to cover all the cases.

Webhook filters

Rules can now look beyond the version name. When a push or pull request webhook is received, a rule can also match against:

• Changed files — using fnmatch patterns (e.g. docs/*.rst, .readthedocs.yaml).
• Commit message — using a Python regular expression (e.g. ^docs:).
• Pull request labels — using a Python regular expression (e.g. ^(docs|build)$).

All the configured filters must match for the rule to fire.

New "Trigger build" action

Combined with webhook filters, the new Trigger build for version action lets you only build when something relevant changed. A few use cases this enables:

• Skip builds for commits that don't touch the docs (e.g. only build when files under docs/ change).
• Skip builds for commits whose message contains [skip ci].
• Only build pull requests that carry a documentation label.

When a project has at least one enabled "Trigger build" rule, builds are gated by those rules: if no rule matches the incoming webhook event, the build is skipped.

Enable/disable a rule without deleting it

Each rule now has an Enabled toggle, so you can temporarily turn a rule off without losing its configuration.

Where it works

Webhook filters rely on the data sent by your Git provider. For now, they are supported on projects connected through our GitHub App integration. Version-only rules (the existing "Activate version", "Hide version", etc.) keep working on every provider as before.

Migration

If you already have automation rules configured, there is nothing you need to do. All your existing rules have been migrated to the new model and continue to work the same way. You will simply find new fields available the next time you edit them.

Try it out

Head over to your project's Settings → Automation rules page to take it for a spin, and check our documentation on automation rules for the full reference and more examples.

As always, let us know what you think or open an issue if you hit any rough edges.