docs(repos): add allow_events remodel documentation (#394)

go-vela · Feb 12, 2024 · 2d3e3a6 · 2d3e3a6
1 parent f7b6292
commit 2d3e3a6
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 7 deletions.
diff --git a/content/reference/cli/repo/add.md b/content/reference/cli/repo/add.md
@@ -98,5 +98,6 @@ allowpush: true
 allowdeploy: false
 allowtag: false
 allowcomment: false
+allowevents: [push pull_request:opened pull_request:synchronize ]
 pipelinetype: yaml
 ```
diff --git a/content/reference/cli/repo/update.md b/content/reference/cli/repo/update.md
@@ -47,6 +47,16 @@ This command also supports setting the following parameters via a configuration
 For more information, please review the [CLI config documentation](/docs/reference/cli/config/).
 {{% /alert %}}
 
+{{% alert color="warning" %}}
+As of Vela `v0.23.0`, the `event` flag is an overwrite/clobber operation. 
+
+```sh
+$ vela update repo --org github --repo octocat --event tag
+```
+
+The above will set the allowed events to only `tag`. Be sure to specify _all_ events when updating a repo via the CLI.
+{{% /alert %}}
+
 ## Permissions
 
 COMING SOON!
@@ -98,5 +108,6 @@ allowpush: true
 allowdeploy: false
 allowtag: true
 allowcomment: false
+allowevents: [tag]
 pipelinetype: yaml
 ```
diff --git a/content/reference/yaml/steps.md b/content/reference/yaml/steps.md
@@ -168,6 +168,21 @@ steps:
       # Specifying comment is the same as [comment:created, comment:edited]. 
 ```
 
+{{% alert color="info" %}}
+Event scoping (`event:action`) was included in Vela release `v0.23.0`. As such, general `event` rulesets in pipelines are mapped as following:
+
+- `pull_request` -> [ `pull_request:opened`, `pull_request:synchronize`, `pull_request:reopened` ]
+- `comment` -> [ `comment:created`, `comment:edited` ]
+- `deployment` -> [ `deployment:created` ]
+
+If you wish to include _all_ event types from an event, you can specify a wildcard at the end:
+
+```yaml
+    ruleset:
+      event: pull_request*  # will run on opened, reopened, synchronize, and edited
+```
+{{% /alert %}}
+
 ```yaml
 ---
 steps:

diff --git a/content/usage/repo_settings.md b/content/usage/repo_settings.md
@@ -19,16 +19,31 @@ Below are all settings for repositories that can be changed in the Vela UI / CLI
 
 Vela can subscribe to any of the following webhook events:
 
-| Event           | Description                                             |
-|-----------------|---------------------------------------------------------|
-| `push`          |  a commit pushed to a repository branch                 |
-| `pull_request`  |  a pull request is opened or updated with a new commit  |
-| `tag`           |  a commit tag is pushed to the repository               |
-| `deployment`    |  a deployment is created for the repository             |
-| `comment`       |  a comment has been made on a pull request              |
+| Event                         | Description                                                                |
+|------------------------------ |--------------------------------------------------------------------------- |
+| `push`                        |  a commit pushed to a repository branch                                    |
+| `tag`                         |  a commit pushed to a repository branch                                    |
+| `pull_request:opened`         |  a pull request is opened                                                  |
+| `pull_request:reopened`       |  a pull request is reopened                                                |
+| `pull_request:synchronize`    |  a pull request source branch has been updated with a new commit           |
+| `pull_request:edited`         |  a pull request has been edited (title, description, target branch, etc)   |
+| `deployment:created`          |  a deployment is created for the repository                                |
+| `comment:created`             |  a comment has been made on a pull request                                 |
+| `comment:edited`              |  a comment has been edited on a pull request                               |
+| `delete:branch`               |  a repository branch has been deleted                                      |
+| `delete:tag`                  |  a repository tag has been deleted                                         |
 
 Pipelines can be written to behave differently based on which event triggered the build (see [rulesets](/docs/tour/rulesets)).
 
+{{% alert color="info" %}}
+Event scoping (`event:action`) was included in Vela release `v0.23.0`. As such, general `event` rulesets in pipelines are mapped as following:
+
+- `pull_request` -> [ `pull_request:opened`, `pull_request:synchronize`, `pull_request:reopened` ]
+- `comment` -> [ `comment:created`, `comment:edited` ]
+- `deployment` -> [ `deployment:created` ]
+
+{{% /alert %}}
+
 Updating webhook events for a Vela repository _must_ be done through Vela (API/CLI/UI) in order to preserve the signature integrity of the webhook. Otherwise, users will experience a [webhook signature error](/docs/faq/usage/#payload-signature-check-failed).
 
 ### Access