Buffy is configured using a simple YAML file containing all the settings needed. The settings file is located in the
/config dir and is named
<environment> is the name of the environment Buffy is running in, usually set via the RACK_ENV env var. So for a Buffy instance running in production mode, the configuration file will be
A sample settings file will look similar to this:
buffy: env: bot_github_user: <%= ENV['BUFFY_BOT_GH_USER'] %> gh_access_token: <%= ENV['BUFFY_GH_ACCESS_TOKEN'] %> gh_secret_token: <%= ENV['BUFFY_GH_SECRET_TOKEN'] %> teams: editors: 3824115 eics: myorg/editor-in-chief-team responders: help: hello: hidden: true assign_editor: only: editors remove_editor: only: editors no_editor_text: "TBD" list_of_values: - reviewers: only: editors if: role_assigned: editor reject_msg: "Can't assign reviewer because there is no editor assigned for this submission yet" sample_value: "@username" add_as_assignee: true invite: only: eics set_value: - version: only: editors sample_value: "v1.0.0" - archive: only: editors sample_value: "10.21105/joss.12345" welcome:
The structure of the settings file starts with a single root node called
It contains three main parts:
A detailed description of all of them:
Env: General configuration settings
env: bot_github_user: <%= ENV['BUFFY_BOT_GH_USER'] %> gh_access_token: <%= ENV['BUFFY_GH_ACCESS_TOKEN'] %> gh_secret_token: <%= ENV['BUFFY_GH_SECRET_TOKEN'] %> templates_path: ".templates"
The env section is used to declare general key/value settings. For security reasons is a good practice to load the secret values from your environment instead of hardcoding them in the code.
- The name of the bot. It is the GitHub user that will respond to commands. It should have admin permissions on the reviews repo. The default value is reading it from the BUFFY_BOT_GH_USER environment variable.
- The GitHub developer access token for the bot user. The default value is reading it from the BUFFY_GH_ACCESS_TOKEN environment variable.
- The GitHub secret token configured for the webhook sending events to Buffy. The default value is reading it from the BUFFY_GH_SECRET_TOKEN environment variable.
- The relative path in the target repo where templates are located. This path is used by responders replying with a message built from a template. The default value is
teams: editors: 3824117 eics: myorg/editor-in-chief-team reviewers: 45363564 collaborators: - user33 - user42
The optional teams node includes entries to reference GitHub teams, used later to grant access to responders only to users belonging to specific teams. The teams referred here must be visible teams of the organization owner of the repositories where the reviews will take place. Multiple entries can be added to the teams node. All entries follow this simple format:
- key: value
- Where key is the name for this team in Buffy and value can be:
- - The integer id of the team in GitHub (preferred)
- - The reference in format organization/name (for example: openjournals/editors)
- - An array of user handles
responders: help: hello: hidden: true assign_reviewers: only: editors
The responders node lists all the responders that will be available. The key for each entry is the name of the responder and nested under it the configuration options for that responder are declared.
All the responders share some options available to all of them. They can also have their own particular configurable parameters (see docs for each responder). The common parameters are:
- Defaults to false. If true this responder won't be listed in the help provided to users.
... secret_responder: hidden: true ...
- List of teams (referred by the name used in the teams node) that can have access to the responder. Used to limit access to the responder. If only and authorized_roles_in_issue are not present the responder is considered public and every user in the repository can invoke it.
public_responder: available_for_one_team_responder: only: editors available_for_two_teams_responder: only: - editors - reviewers
- List of values in the body of the issue marked with HTML comments that contains user(s) allowed to run the responder. Used to grant access to the responder per issue. If only and authorized_roles_in_issue are not present the responder is considered public and every user in the repository can invoke it.
public_responder: restricted_responder: only: editors authorized_roles_in_issue: - author-handle - reviewers-list
(restricted_responder can only be called by members of the editors team and by users listed in the issue in the author-handle and reviewers-list HTML-marked fields)
- This setting is used to impose conditions on the responder. It can include several options:
<String> or <Regular Expresion> Responder will run only if issue’ title matches this.
<String> or <Regular Expresion> Responder will run only if the body of the issue matches this.
<String> Responder will run only if there is a not empty value for this in the issue (marked with HTML comments).
<Hash> Responder will run only if the param values (marked with HTML comments) in the body of the issue matches the ones specified here.
<String> Responder will be run only if there is a username assigned for the specified value.
<Array> Responder will be run only if the issue is labeled with all the labels listed here.
<String> Optional. The response to send as comment if the conditions are not met
# This responder should be invoked only if there's an editor assigned # otherwise will reply with a custom "no editor assigned yet" message assign_reviewer: if: role_assigned: editor reject_msg: I can not do that because there is no editor assigned yet # This responder will run only if issue title includes '[PRE-REVIEW]' and if # there is a value for repo-url, ie: <!--repo-url-->whatever<!--end-repo-url--> start_review: if: title: "^\\[PRE-REVIEW\\]" value_exists: repo-url # This responder will run only if the value for submission_type in the body of # the issue matches 'astro', ie: <!--submission_type-->astro<!--end-submission_type--> start_review: if: value_matches: submission_type: astro # This responder will run only if issue title includes '[REVIEW]' and # the issue is labeled as 'accepted start_review: if: title: "^\\[REVIEW\\]" labels: - accepted
- Every responder has a default description to be shown using the help_responder. Use this param if you want to use a custom description.
... custom_responder: description: "This responder do something" ...
- Every responder defines an example string showing the command to invoke it, to be listed using the help_responder. Use this param if for some reason you want to use a custom value for the example invocation.
... custom_responder: example_invocation: "@botname run performance checks (please run this only on mondays)" ...
A complete example:
# Two responders are configured here: # # The assign_reviewers responder will respond only when triggered by a user that is # member of any of the editors or editors-in-chief teams. It will also respond only # in issues with the text "[REVIEW]" in its title and that have a not empty value # in its body marked with HTML comments: <!--editor-->@EDITOR_HANDLE<!--end-editor--> # Once invoked, it will label the issue with the 'reviewers-assigned' label. # # The hello responder is configured as hidden, so when calling the help responder the # description and usage example of the hello responder won't be listed in the response. ... responders: assign_reviewers: only: - editors - editors-in-chief if: title: "^\\[REVIEW\\]" role_assigned: editor add_labels: - reviewers-assigned description: "Use this command to assign a reviewers once the editor is assigned" hello: hidden: true ...
Several responders also allow adding or removing labels.
Multiple instances of the same responder
Sometimes you want to use a responder more than once, with different parameters. In that case under the name of the responder you can declare an array of instances, and the key for each instance will be passed to the responder as the
The set_value responder uses a
name param to change the value to a variable. If declared in the settings file like this:
responders: set_value: name: version
It could be invoked with
@botname set 1.0 as version.
If you want to use the same responder to change
version but also to allow editors to change
url you would declare multiple instances in the settings file like this:
responders: set_value: - version: - url: only: editors
@botname set 1.0 as version is a public command and
@botname set abcd.efg as url is a command available to editors.