Installation

Honk started out as a utility script for developers, and has evolved into the service you see today. Its aim is to be an integration platform between services commonly used by developers, to provide a useful set of features.

Upon first authenticating to Honk, a check will be made to see if your existing Slack workspace has already signed up. If it has, you are simply authenticated as yourself. Otherwise, you will be prompted to install Honk to your Slack workspace. This is needed in order to notify the desired channels and users of matching events.

You will then be redirected to a dashboard page if you are subscribed, or a subscription page otherwise.

For trials and customised offers, please contact us!

Great, now you have a Slack integration and the ability to send messages, you are just missing the data source. For that, you will need to integrate Honk to your GitHub organisation, in order to get notified of all necessary events.

Once both the Slack and the GitHub apps have been installed, you will need to provide Honk with a configuration.

Config

You can provide Honk with a configuration through the use of a POST request to https://gethonk.io/rules/upload.

For this, you will need to follow a series of steps:

Create a token on your honk dashboard. Once created, make a note of it, it will appear at the top of the page only once.
Create a configuration file and upload it.
- The best approach for this is to host this configuration inside a GitHub repository. You can automate the upload process through the use of a GitHub action. This is where the token comes into play. Add that as a repository secret

Example GitHub action

# .github/workflows/upload_config.yml
on:
   push:
      paths:
         - 'rules.yaml'
         - '.github/workflows/upload_config.yml'

jobs:
   upload_config:
      runs-on: ubuntu-latest
      steps:
         - uses: actions/checkout@v3
         - id: upload_config_staging
           uses: oneroar/upload-config@main
           with:
              token: ${{ secrets.token }}

If you would rather upload the configuration manually, the upload-config job does the following thing

curl --write-out '%{http_code}' \
     --silent --output /dev/null \
     -X POST  -H "X-Honk-Token:$TOKEN" \
     https://gethonk.io/rules/upload/ \
     -F "file_uploaded=@rules.yaml" --fail

Honk Config format

This guide explains how to structure your data in YAML format to match the JSON schema requirements.

Rule Object

A Rule object consists of the following properties:

name (string, required): The name of the rule.
rules (array of arrays of Filter objects, required): An array of arrays containing Filter objects.
notify (object of Notify type, required): An object with notification settings.

Example Rule Object in YAML:

name: My Rule
rules:
  - # Array of Filter objects
    - by: field1
      one_of: [value1, value2]
    - by: field2
      contains: [text1, text2]
  - # Array of Filter objects
    - by: field3
      one_of: [value3]
notify:
  channels:
    - channel1
    - channel2
  users:
    - user1
    - user2
  verbose: true

Filter Object

A Filter object represents a filtering condition and includes the following properties:

by (string, required): The field to filter by. Possible values include:
- pull_request.author
- pull_request.title
- pull_request.reviewer
- repository
- discussion.author
- discussion.label
- discussion.category
- discussion.title
one_of (array of strings or null, optional): An array of allowed values. Use null if not needed.
contains (array of strings or null, optional): An array of values to check for containment. Use null if not needed.
negate (boolean, optional): Set to true to negate the filter.

Example Filter Object in YAML:

- by: field1
  one_of: [value1, value2]
- by: field2
  contains: [text1, text2]
- by: field3
  negate: true

Notify Object

A Notify object contains notification settings:

channels (array of strings): An array of notification channels.
users (array of strings): An array of user IDs.
verbose (boolean): Set to true for verbose notifications.

You can provide your data following these guidelines in YAML format. Ensure that the indentation is correct, and the structure matches the examples provided.

Honk Docs