rename gh_webhook_secret and update config.atd comments

Author: yasunariw

documentation/secret_docs.md

@@ -43,8 +43,8 @@ Secret file is where sensitive information such as the urls used for webhooks an
 | value | description | optional | default |
 |-|-|-|-|
 | `slack_hooks` | list of webhook config objects | No | - |
-| `gh_token` | must not be specified for public repositories | Yes | - |
-| `gh_webhook_secret` | if not specified signatures will not be checked | Yes | - |
+| `gh_token` | specify to grant the bot access to private repositories; omit for public repositories | Yes | - |
+| `gh_hook_token` | specify to ensure the bot only receives GitHub notifications from pre-approved repositories | Yes | - |
 
 ## `gh_token`
 
@@ -64,8 +64,8 @@ Some event notifications (e.g., status, commit comment) require a personal token
 For more detailed instructions on token generation, refer to https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line.
 
 
-## `gh_webhook_secret`
-For more information on `gh_webhook_secret` see [developer.github.com/webhooks/securing](https://developer.github.com/webhooks/securing/)
+## `gh_hook_token`
+For more information on `gh_hook_token` see [developer.github.com/webhooks/securing](https://developer.github.com/webhooks/securing/)
 
 ## Webhook Config
 

lib/config.atd

@@ -8,16 +8,16 @@ type status_rules = {
   rules: status_state;
 }
 
-(* This type of rule is used for CI build notifications. *)
+(* This type of rule is used for events that must be routed based on the
+  files they are related to. *)
 type prefix_rules = {
-  ?default_channel : string nullable; (* if none of the rules is matching *)
+  ?default_channel: string nullable; (* if none of the rules is matching *)
   rules: prefix_rule list;
 }
 
-(* This type of rule is used for events that must be routed based on the
-  files they are related to. *)
+(* This type of rule is used for PR and issue notifications. *)
 type label_rules = {
-  ?default_channel : string nullable; (* if none of the rules is matching *)
+  ?default_channel: string nullable; (* if none of the rules is matching *)
   rules: label_rule list;
 }
 
@@ -33,14 +33,14 @@ type config = {
 
 (* This specifies the Slack webhook to query to post to the channel with the given name *)
 type webhook = {
-  url : string; (* url to call to send the message *)
-  channel : string; (* name of the channel where the message will be posted *)
+  url : string; (* webhook URL to post the Slack message *)
+  channel : string; (* name of the Slack channel to post the message *)
 }
 
 (* This is the structure of the secrets file which stores sensitive information, and
    shouldn't be checked into version control.  *)
 type secrets = {
   slack_hooks : webhook list;
-  ?gh_token : string option; (* must not be specified for public repositories *)
-  ?gh_webhook_secret : string option; (* if not specified - signatures will not be checked *)
+  ?gh_token : string option; (* GitHub personal access token, if repo access requires it *)
+  ?gh_hook_token : string option; (* GitHub webhook token to secure the webhook *)
 }

lib/config.ml

@@ -15,7 +15,7 @@ type t = {
   chans : string Chan_map.t;
   prefix_rules : Config_t.prefix_rules;
   label_rules : Config_t.label_rules;
-  gh_webhook_secret : string option;
+  gh_hook_token : string option;
   main_branch_name : string option;
   gh_token : string option;
   offline : string option;
@@ -89,7 +89,7 @@ let make (json_config : Config_t.config) (secrets : Config_t.secrets) =
     chans;
     prefix_rules = json_config.prefix_rules;
     label_rules = json_config.label_rules;
-    gh_webhook_secret = secrets.gh_webhook_secret;
+    gh_hook_token = secrets.gh_hook_token;
     main_branch_name = json_config.main_branch_name;
     gh_token = secrets.gh_token;
     offline = json_config.offline;

src/notabot.ml

@@ -14,7 +14,7 @@ let cfg_action_after_refresh (cfg : Config.t) =
   Rule.Prefix.print_prefix_routing cfg.prefix_rules.rules;
   log#info "using label routing:";
   Rule.Label.print_label_routing cfg.label_rules.rules;
-  log#info "signature checking %s" (if Option.is_some cfg.gh_webhook_secret then "enabled" else "disabled")
+  log#info "signature checking %s" (if Option.is_some cfg.gh_hook_token then "enabled" else "disabled")
 
 let update_state_at_path state_path state event = State.save state_path @@ State.update_state state event