Configuration

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 settings-<environment>.yml, where <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 /config/settings-production.yml

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:

File Structure

The structure of the settings file starts with a single root node called buffy. It contains three main parts:

The env node
The teams node
The responders node

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.

bot_github_user: 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.
gh_access_token: The GitHub developer access token for the bot user. The default value is reading it from the BUFFY_GH_ACCESS_TOKEN environment variable.
gh_secret_token: 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.
templates_path: 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 .buffy/templates.

Teams

  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

  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.

Common options

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:

hidden

Defaults to false. If true this responder won't be listed in the help provided to users.

Usage:

  ...
  secret_responder:
    hidden: true
  ...

only

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.

Usage:

  public_responder:
  available_for_one_team_responder:
    only: editors
  available_for_two_teams_responder:
    only:
      - editors
      - reviewers

authorized_roles_in_issue

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.

Usage:

  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)

if

This setting is used to impose conditions on the responder. It can include several options:

title:: <String> or <Regular Expresion> Responder will run only if issue’ title matches this.
body:: <String> or <Regular Expresion> Responder will run only if the body of the issue matches this.
value_exists:: <String> Responder will run only if there is a not empty value for this in the issue (marked with HTML comments).
value_matches:: <Hash> Responder will run only if the param values (marked with HTML comments) in the body of the issue matches the ones specified here.
role_assigned:: <String> Responder will be run only if there is a username assigned for the specified value.
labels:: <Array> Responder will be run only if the issue is labeled with all the labels listed here.
reject_msg:: <String> Optional. The response to send as comment if the conditions are not met

Usage:

  # 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

description

Every responder has a default description to be shown using the help_responder. Use this param if you want to use a custom description.

Usage:

  ...
  custom_responder:
    description: "This responder do something"
  ...

example_invocation

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.

Usage:

  ...
  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 name parameter.

Example:

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

Now @botname set 1.0 as version is a public command and @botname set abcd.efg as url is a command available to editors.