Build: webhook filters `v2`

[humitos]

I'm not sure where this feature will arrive at just yet, but I'm leaving an idea that I think it could work while thinking in the redesign of this feature. We can discuss this, and other ideas here, and decide the next iterative steps.

Also, thinking more I do think it makes sense to have these merged with the existing rules, it doesn't make much sense now, but I think we should adapt the rules to allow for composition in the future (if a version name matches x and its commit matches y, do this action). When to run the rules is already defined by action (on version creation, deletion, push).

Yeah, this is a good idea we can explore 👍🏼 . I think we are creating a big generic feature here that we will be able to combine with other features that already exist to make them more powerful.

We probably want to redesign this as:

• version matching: match the name/slug (eg. release-*) of the version and the type of it (e.g tag)
• webhook filter: filter files pushed in the commit (e.g. docs/*.rst)
• action: perform an action (e.g. trigger a build)

This is just an idea, we need to sit down and think more broadly about this, but definitely it's a feature with a lot of power that we should redesign to grab all these uses cases in a easy way to communicate.

Originally posted by @humitos in #12697 (comment)

[humitos]

webhook filter: filter files pushed in the commit (e.g. docs/*.rst)

I mentioned files here, but it could be tags, commit message, etc. See #12707 for more ideas and links to other issues.

[humitos]

I'm thinking we can model this idea of

• version type where the rule will be applied (eg. tag, external, etc)
• version name pattern to be checked (eg. release-*)
• webhook filter type where we need to apply the filter (eg. labels)
• webhook pattern to be applied in that filter (eg. docs)
• action to be excuted (eg. trigger a build)

as follows:

class AutomationRule:
  # allows to select more than one to apply the same rule to multiple version types
  version_filter = ["tag", "branch", "external"]

  # regex pattern to apply to the version name
  version_match_pattern = "^release-.*"

  # allows only one
  # `None` means that webhooks won't be filtered
  webhook_filter = [None, "label", "commit_message", "file_pattern"]

  # pattern to apply to the `webhook_filter` selected
  # it could be a regex or file pattern depending on `webhook_filter`
  webhook_match_pattern = "*.rst" 

  # depends on `webhook_filter`
  # `None`: supports only version management (create, activate, delete, etc)
  # "label", "commit_message", "file_pattern": supports "(not)trigger build" only for now
  action = ["create version", "delete version", "activate version" "trigger build", etc]

  # Other required fields
  project = ForeignKey(Project)
  priority = PositiveIntegerField()
  description = TextField()

I think with this modeling we can cover all the use cases we have in mind now. I'm open to bring more use cases here so we can think more and expand the modeling. I don't think we need to complicate things here and stay with basic Django models, removing polymorphic and any other fancy/magic thing we built here.

Examples

Skip triggering build based on commit message for all the versions

AutomationRule:
  version_filter = "any"
  version_match_pattern = ".*"
  webhook_filter = "commit_message"
  webhook_match_pattern = ".*skip ci.*"
  action = "skip triggering build"

Trigger builds only on modified files

AutomationRule:
  version_filter = "any"
  version_match_pattern = ".*"
  webhook_filter = "file_pattern"
  webhook_match_pattern = [".readthedocs.yaml", "docs/*", "requirements/docs.txt"]
  action = "triggering build"

Activate release-* versions

AutomationRule:
  version_filter = "tag"
  version_match_pattern = "release-.*"
  webhook_filter = None
  webhook_match_pattern = None
  action = "activate version"

[stsewd]

My idea for composition would be something like.

class AutomationRule:
    matchers = RuleMatcher
    operator # and/or
    action # (or maybe actions?)
    project
    position

class RuleMatcher:
    type # commit/version name/version type/files changed
    argument

Then users can create a rule with several matches to perform an action if all or at least one matcher succeeds. The matchers that can be used would depend on the action if we find restrictions.

Could also be simplified for the operator to always be "and", since an "or" is the same as creating several rules for the same action.

[humitos]

We discussed this yesterday and it seems we are all on board. We touched on Santos' modeling and we decided that we could start with the simpler modeling first, and maybe migrate to the RuleMatcher in the future if we detect we need more complex matching rules.

Anthony mentioned we could consider the "default automation rules" (stable and latest alias) to always be shown in the UI and maybe give the ability to the user to turn them on/off. In the future we could consider other type of customization for these default rules, but we don't want to complicate it from the beginning. I'd leave this type of customization out of the scope of this initial work.

Anthony said there are a couple of customers with a lot of automation rules we could get ideas from for use cases that I may haven't thought yet and check if the new modelling works on those cases as well.

UI will be similar to what we currently have. The listing may no need any modification and the detail form would need to be similar to the redirects one where some fields are enabled/disabled based on a value on another input and there will be input that changes their choices (eg. actions) based on the value of another input (eg. webhook_filter).

[agjohnson]

One thing we haven't talked about recently is how this would affect webhooks from other providers. We initially just supported GitHub app connected repositories, but if we're making a general feature like more automation rules around this, I suppose that would imply we would also support other connected providers. Is this in the plan?

[humitos]

how this would affect webhooks from other providers

I'm not considering other providers in this stage. I plan to make it work only for GitHub App. I think we have been considering GitHub the main VCS provider and where we will put our efforts. As an example, the PR summary comment only works on GitHub App.