Example documentation for filtering webhooks based on repo and path

[mrled]

Is your feature request related to a problem? Please describe.
I had some trouble figuring out how to filter webhooks from Gitea based on repository name and path. I think GitHub uses approximately the same webhook payloads and so documentation should translate between the two.

Describe the solution you'd like
An example showing how to do this

Describe alternatives you've considered
You can piece it together from the docs, examples, some closed issues/PRs, and the GJSON and Go regexp docs, but I think at least the way that GJSON works is missing from the docs. I see this PR contains some documentation but I don't see it anywhere in the tutorial today...

I also think a complete example of this particular use case might be worth an end-to-end example.

Additional context
Here's the comment I wrote to myself about how this works in my own repo. I don't have time to submit a real docs PR at the moment, but I hope this note has enough information in one place to be valuable anyway.

      # Only trigger for paths under /path/to/somewhere on the owner/reponame repo
      filters:
        # All of the data filters must match
        dataLogicalOperator: "and"

        data:
          # Match on a repo called "reponame" owned by a user/org named "owner"
          - path: body.repository.full_name
            type: string
            value:
              - "owner/reponame"

          # At least one of the modified/created/deleted files
          # has to be in /path/to/somewhere/
          # https://github.com/argoproj/argo-events/issues/1127
          # https://github.com/argoproj/argo-events/issues/1097
          #
          # Original docs on this syntax:
          # https://github.com/argoproj/argo-events/pull/1130/files
          # That seems to have been lost from the current docs?
          #
          # The path attribute is using GJSON Path Syntax
          # https://github.com/tidwall/gjson/blob/master/SYNTAX.md#multipaths
          #
          # The value attribute should be a single value (?) using Go regexp syntax
          # https://pkg.go.dev/regexp/syntax
          #
          # The Gitea webhook mostly is GitHub compatible.
          # Both send a rather large JSON payload, including a list of commits
          # and a list of files modified/added/removed in each.
          # So our GJSON path value will parse a payload like this one (heavily truncated):
          # {
          #   "body": {
          #     "commits": [
          #       {
          #         "modified": [
          #           "path/to/somewhere/README.md",
          #          ]
          #       }
          #     ]
          #   }
          # }
          # into a JSON list of all the files modified/added/removed, like this:
          # ["path/to/somewhere/README.md"]
          #
          # The Go regexp then acts on THAT RESULT.
          #
          # With that in mind, we can write regexps that assume a double-quote
          # marks the beginning and end of a filename.
          # I do not bother trying to be robust enough to handle filenames with double quotes in them,
          # if your repo has that GFYS.
          - path: "[body.commits.#.modified.@flatten,body.commits.#.added.@flatten,body.commits.#.removed.@flatten].@flatten.@flatten"
            type: string
            value:
              - '"path/to/somewhere/.*"'

---

Message from the maintainers:

If you wish to see this enhancement implemented please add a 👍 reaction to this issue! We often sort issues this way to know what to prioritize.